| Name | pilfer JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | Decrypt all ansible vault files in a project recursively for search/editing, then re-encrypt when done. |
| upload_time | 2025-07-19 20:19:32 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | None |
| keywords |
ansible
vault
encryption
devops
automation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pilfer
Decrypt *all* ansible vault files in a project recursively for search/editing, then re-encrypt them all at once when you're done.
Borrows heavily from the excellent, but no longer supported [Ansible Toolkit](https://github.com/dellis23/ansible-toolkit).
**Updated for Python 3 compatibility with modern features and ansible.cfg integration.**
Tested with Ansible v2.18.x and Python 3.12.x
## Features
- **Python 3 compatible** - Modernized for current Python versions
- **ansible.cfg integration** - Automatically reads `vault_password_file` from your ansible.cfg
- **Change detection** - Only re-encrypts files that were actually modified (using SHA256)
- **Safe operation** - Preserves original encrypted content for unchanged files
- **No third-party dependencies** - Uses Ansible's official vault implementation directly
- **Binary data preservation** - Preserves exact line endings and formatting (critical for certificates)
## Usage
```
pilfer [open|close] [-p VAULT_PASSWORD_FILE]
```
### Basic Usage
**Option 1: Standalone Script (No Installation)**
- Download `pilfer.py` and place it in your Ansible project directory
- Run `python pilfer.py open` to decrypt all vaulted files recursively
- Edit/search plaintext as needed
- Run `python pilfer.py close` to re-encrypt any changed files
**Option 2: Installed via pipx (Recommended)**
- Install pilfer via pipx: `pipx install pilfer`
- Run `pilfer open` to decrypt all vaulted files recursively
- Edit/search plaintext as needed
- Run `pilfer close` to re-encrypt any changed files
Any unchanged files will be returned to their original state.
### Vault Password File Detection
The script automatically detects your vault password file in this order:
1. **Command line argument**: `-p /path/to/vault/file`
2. **ansible.cfg**: Reads `vault_password_file` from `[defaults]` section
3. **Common locations**:
- `~/.ansible-vault/.vault-file`
- `../../vault_password_file`
- `.vault_password`
- `vault_password_file`
### Examples
**Using the installed version:**
```bash
# Use ansible.cfg vault_password_file setting (recommended)
pilfer open
# Specify custom vault password file
pilfer open -p ~/.my-vault-password
# Close and re-encrypt modified files
pilfer close
```
**Using the standalone script:**
```bash
# Use ansible.cfg vault_password_file setting (recommended)
python pilfer.py open
# Specify custom vault password file
python pilfer.py open -p ~/.my-vault-password
# Close and re-encrypt modified files
python pilfer.py close
```
## Installation
### Option 1: Standalone Script (No Installation Required)
Download and use the standalone script directly:
```bash
# Download the standalone script
curl -O https://raw.githubusercontent.com/aioue/pilfer/main/pilfer.py
# Make it executable (required for ./pilfer.py usage)
chmod +x pilfer.py
# Use it directly
./pilfer.py open
# OR
python pilfer.py open
```
### Option 2: Install via pipx (Recommended for Regular Use)
**Python 3.6+** is required. Install pilfer using pipx for isolated CLI tool management:
```bash
# Install pilfer via pipx (recommended)
pipx install pilfer
# Verify installation
pilfer --help
```
### Alternative Installation Methods
If you prefer other installation methods:
```bash
# Install from source (in development mode)
git clone https://github.com/aioue/pilfer.git
cd pilfer
pip install -e .
# Direct pip installation (not recommended for CLI tools)
pip install pilfer
```
### Requirements
Pilfer requires **Ansible** to be available. If not already installed:
```bash
# Using pipx (recommended for CLI tools)
pipx install ansible
# Using pip
pip install ansible
# System package manager
# Ubuntu/Debian:
sudo apt update && sudo apt install ansible
# RHEL/CentOS/Fedora:
sudo dnf install ansible
# macOS:
brew install ansible
```
### ansible.cfg Setup (Recommended)
Add to your `ansible.cfg`:
```ini
[defaults]
vault_password_file = ~/.ansible-vault/.vault-file
```
This eliminates the need to manually configure vault password paths.
## Development and Publishing
### For Developers
To set up for development:
```bash
# Clone the repository
git clone https://github.com/aioue/pilfer.git
cd pilfer
# Install in development mode
pip install -e .
# Make changes and test
pilfer --help
```
### Publishing to PyPI
Prerequisites:
```bash
# Install build tools
pip install build twine
# Configure PyPI credentials
# ~/.pypirc or use environment variables
```
Build and publish:
```bash
# Make the script executable
chmod +x build_and_publish.sh
# Publish to TestPyPI first
./build_and_publish.sh test
# After testing, publish to production PyPI
./build_and_publish.sh prod
```
The build script will:
1. Clean previous builds
2. Build the package using modern Python packaging
3. Upload to PyPI/TestPyPI using twine
4. Provide installation instructions
## License
This project is licensed under the GNU General Public License v3 or later (GPLv3+). See the [LICENSE](LICENSE) file for the complete license text from the [official GNU website](https://www.gnu.org/licenses/gpl-3.0.txt).
### Packaging Note
Due to a compatibility issue between modern setuptools (which supports SPDX license expressions) and PyPI's current metadata validation (which doesn't yet support the new format), the license file is renamed to `PILFER_LICENSE.txt` during packaging to avoid auto-detection issues. This is a temporary workaround until PyPI updates its metadata validation to support the newer standards.
This package heavily borrows from the excellent, but no longer supported [Ansible Toolkit](https://github.com/dellis23/ansible-toolkit).
Raw data
{
"_id": null,
"home_page": null,
"name": "pilfer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "ansible, vault, encryption, devops, automation",
"author": null,
"author_email": "Tom Paine <github@aioue.net>",
"download_url": "https://files.pythonhosted.org/packages/cb/52/b921fadafabe2288bcede6799e41e6e08f3ed5904997935298206a84c545/pilfer-1.0.2.tar.gz",
"platform": null,
"description": "# pilfer\nDecrypt *all* ansible vault files in a project recursively for search/editing, then re-encrypt them all at once when you're done.\n\nBorrows heavily from the excellent, but no longer supported [Ansible Toolkit](https://github.com/dellis23/ansible-toolkit).\n\n**Updated for Python 3 compatibility with modern features and ansible.cfg integration.**\n\nTested with Ansible v2.18.x and Python 3.12.x\n\n## Features\n\n- **Python 3 compatible** - Modernized for current Python versions\n- **ansible.cfg integration** - Automatically reads `vault_password_file` from your ansible.cfg\n- **Change detection** - Only re-encrypts files that were actually modified (using SHA256)\n- **Safe operation** - Preserves original encrypted content for unchanged files\n- **No third-party dependencies** - Uses Ansible's official vault implementation directly\n- **Binary data preservation** - Preserves exact line endings and formatting (critical for certificates)\n\n## Usage\n```\npilfer [open|close] [-p VAULT_PASSWORD_FILE]\n```\n\n### Basic Usage\n\n**Option 1: Standalone Script (No Installation)**\n- Download `pilfer.py` and place it in your Ansible project directory\n- Run `python pilfer.py open` to decrypt all vaulted files recursively\n- Edit/search plaintext as needed\n- Run `python pilfer.py close` to re-encrypt any changed files\n\n**Option 2: Installed via pipx (Recommended)**\n- Install pilfer via pipx: `pipx install pilfer`\n- Run `pilfer open` to decrypt all vaulted files recursively\n- Edit/search plaintext as needed\n- Run `pilfer close` to re-encrypt any changed files\n\nAny unchanged files will be returned to their original state.\n\n### Vault Password File Detection\n\nThe script automatically detects your vault password file in this order:\n\n1. **Command line argument**: `-p /path/to/vault/file`\n2. **ansible.cfg**: Reads `vault_password_file` from `[defaults]` section\n3. **Common locations**: \n - `~/.ansible-vault/.vault-file`\n - `../../vault_password_file` \n - `.vault_password`\n - `vault_password_file`\n\n### Examples\n\n**Using the installed version:**\n```bash\n# Use ansible.cfg vault_password_file setting (recommended)\npilfer open\n\n# Specify custom vault password file\npilfer open -p ~/.my-vault-password\n\n# Close and re-encrypt modified files\npilfer close\n```\n\n**Using the standalone script:**\n```bash\n# Use ansible.cfg vault_password_file setting (recommended)\npython pilfer.py open\n\n# Specify custom vault password file\npython pilfer.py open -p ~/.my-vault-password\n\n# Close and re-encrypt modified files\npython pilfer.py close\n```\n\n## Installation\n\n### Option 1: Standalone Script (No Installation Required)\n\nDownload and use the standalone script directly:\n\n```bash\n# Download the standalone script\ncurl -O https://raw.githubusercontent.com/aioue/pilfer/main/pilfer.py\n\n# Make it executable (required for ./pilfer.py usage)\nchmod +x pilfer.py\n\n# Use it directly\n./pilfer.py open\n# OR\npython pilfer.py open\n```\n\n### Option 2: Install via pipx (Recommended for Regular Use)\n\n**Python 3.6+** is required. Install pilfer using pipx for isolated CLI tool management:\n\n```bash\n# Install pilfer via pipx (recommended)\npipx install pilfer\n\n# Verify installation\npilfer --help\n```\n\n### Alternative Installation Methods\n\nIf you prefer other installation methods:\n\n```bash\n# Install from source (in development mode)\ngit clone https://github.com/aioue/pilfer.git\ncd pilfer\npip install -e .\n\n# Direct pip installation (not recommended for CLI tools)\npip install pilfer\n```\n\n### Requirements\n\nPilfer requires **Ansible** to be available. If not already installed:\n\n```bash\n# Using pipx (recommended for CLI tools)\npipx install ansible\n\n# Using pip\npip install ansible\n\n# System package manager\n# Ubuntu/Debian:\nsudo apt update && sudo apt install ansible\n\n# RHEL/CentOS/Fedora:\nsudo dnf install ansible\n\n# macOS:\nbrew install ansible\n```\n\n### ansible.cfg Setup (Recommended)\n\nAdd to your `ansible.cfg`:\n```ini\n[defaults]\nvault_password_file = ~/.ansible-vault/.vault-file\n```\n\nThis eliminates the need to manually configure vault password paths.\n\n## Development and Publishing\n\n### For Developers\n\nTo set up for development:\n\n```bash\n# Clone the repository\ngit clone https://github.com/aioue/pilfer.git\ncd pilfer\n\n# Install in development mode\npip install -e .\n\n# Make changes and test\npilfer --help\n```\n\n### Publishing to PyPI\n\nPrerequisites:\n```bash\n# Install build tools\npip install build twine\n\n# Configure PyPI credentials\n# ~/.pypirc or use environment variables\n```\n\nBuild and publish:\n```bash\n# Make the script executable\nchmod +x build_and_publish.sh\n\n# Publish to TestPyPI first\n./build_and_publish.sh test\n\n# After testing, publish to production PyPI\n./build_and_publish.sh prod\n```\n\nThe build script will:\n1. Clean previous builds\n2. Build the package using modern Python packaging\n3. Upload to PyPI/TestPyPI using twine\n4. Provide installation instructions\n\n## License\n\nThis project is licensed under the GNU General Public License v3 or later (GPLv3+). See the [LICENSE](LICENSE) file for the complete license text from the [official GNU website](https://www.gnu.org/licenses/gpl-3.0.txt).\n\n### Packaging Note\n\nDue to a compatibility issue between modern setuptools (which supports SPDX license expressions) and PyPI's current metadata validation (which doesn't yet support the new format), the license file is renamed to `PILFER_LICENSE.txt` during packaging to avoid auto-detection issues. This is a temporary workaround until PyPI updates its metadata validation to support the newer standards.\n\nThis package heavily borrows from the excellent, but no longer supported [Ansible Toolkit](https://github.com/dellis23/ansible-toolkit).\n",
"bugtrack_url": null,
"license": null,
"summary": "Decrypt all ansible vault files in a project recursively for search/editing, then re-encrypt when done.",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/aioue/pilfer",
"Issues": "https://github.com/aioue/pilfer/issues",
"Repository": "https://github.com/aioue/pilfer"
},
"split_keywords": [
"ansible",
" vault",
" encryption",
" devops",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7bd9df4db1354d0e38f823570d104a1d52fdf965f499b2b338ee1f5f07fa6269",
"md5": "bb19365fc72800040f34ce9f76bc220c",
"sha256": "ed8a1c504bf5767b5b951efafb483de0ddc6ab0f4199e051fb5621c3e5facfca"
},
"downloads": -1,
"filename": "pilfer-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb19365fc72800040f34ce9f76bc220c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6975,
"upload_time": "2025-07-19T20:19:30",
"upload_time_iso_8601": "2025-07-19T20:19:30.964301Z",
"url": "https://files.pythonhosted.org/packages/7b/d9/df4db1354d0e38f823570d104a1d52fdf965f499b2b338ee1f5f07fa6269/pilfer-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cb52b921fadafabe2288bcede6799e41e6e08f3ed5904997935298206a84c545",
"md5": "d1fa8a5775ecc1f027abd15d149ec2be",
"sha256": "d2683d11995dee6133fd65474e80dee9a4845f7e3461747ad64c5bdb13b8c83f"
},
"downloads": -1,
"filename": "pilfer-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "d1fa8a5775ecc1f027abd15d149ec2be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 19807,
"upload_time": "2025-07-19T20:19:32",
"upload_time_iso_8601": "2025-07-19T20:19:32.020131Z",
"url": "https://files.pythonhosted.org/packages/cb/52/b921fadafabe2288bcede6799e41e6e08f3ed5904997935298206a84c545/pilfer-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 20:19:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aioue",
"github_project": "pilfer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pilfer"
}
