# pwpush CLI
<div align="center">
[](https://github.com/pglombardo/pwpush-cli/actions?query=workflow%3Abuild)
[](https://pypi.org/project/pwpush/)
[](https://github.com/pglombardo/pwpush-cli/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot)
[](https://github.com/psf/black)
[](https://github.com/PyCQA/bandit)
[](https://github.com/pglombardo/pwpush-cli/blob/master/.pre-commit-config.yaml)
[](https://github.com/pglombardo/pwpush-cli/releases)
[](https://github.com/pglombardo/pwpush/blob/master/LICENSE)
**Command Line Interface for Password Pusher**
<br>
Secure information distribution with automatic expiration controls.
</div>
## Overview
The `pwpush` CLI is a powerful command-line tool that interfaces with [Password Pusher](https://pwpush.com) instances for secure information distribution. It supports both the hosted services (eu.pwpush.com, us.pwpush.com) and self-hosted instances.
### Why Secure Information Distribution?
Traditional communication tools create permanent digital footprints that can be exploited years later. Password Pusher sidesteps this by creating:
- **Self-destructing shareable links** that auto-expire after a preset number of views
- **Time-based expiration** that automatically deletes content after a set duration
- **Zero permanent storage** - once expired, the information is completely removed
- **Full audit trails** so you know exactly who accessed what and when
### Key Features
- 🔐 **Secure Information Distribution**: Self-destructing links for passwords, secrets, and files with automatic expiration and complete audit trails.
- 🌐 **Multi-Instance Support**: Works with eu.pwpush.com, us.pwpush.com, or your own instance
- 🔑 **Authentication**: Full API integration with user accounts
- 📊 **Audit Logs**: Track access and usage of distributed content
- 🎯 **Flexible Expiration**: Set expiration by views, days, or both
- 📁 **File Support**: Distribute files securely with the same expiration controls and audit logs
- 🎨 **Rich Output**: Beautiful terminal output with tables and formatting
## Installation
```bash
pip install pwpush
```
**Requirements**: Python 3.9.2 or higher
## Quick Start
### 1. Basic Usage (Anonymous)
```bash
# Push a password (interactive mode)
pwpush push
# Push a password directly
pwpush push --secret "mypassword123"
# Auto-generate a secure password
pwpush push --auto
# Push with custom expiration (7 days, 5 views)
pwpush push --secret "mypassword" --days 7 --views 5
```
### 2. Configure Your Instance
The CLI works with multiple Password Pusher instances:
```bash
# Use the EU instance
pwpush config set --key url --value https://eu.pwpush.com
# Use the US instance
pwpush config set --key url --value https://us.pwpush.com
# Use your own self-hosted instance
pwpush config set --key url --value https://pwpush.yourdomain.com
```
### 3. Authentication (Optional)
For advanced features like listing pushes and audit logs, authenticate with your account:
```bash
# Login with your credentials
pwpush login
# Or set credentials manually
pwpush config set --key email --value your@email.com
pwpush config set --key token --value your_api_token
```
Get your API token from: https://pwpush.com/en/users/token
## Common Commands
### Pushing Content
```bash
# Push a password with custom settings
pwpush push --secret "password123" --days 3 --views 10 --deletable
# Push as URL (for sharing links)
pwpush push --secret "https://example.com" --kind url
# Push as QR code
pwpush push --secret "QR data content" --kind qr
# Push a file
pwpush push-file document.pdf --days 7 --views 5
# Push with a reference note (requires authentication)
pwpush push --secret "password" --note "Employee onboarding - John Doe"
# Require click-through for retrieval (prevents URL scanners)
pwpush push --secret "password" --retrieval-step
```
### Managing Pushes
```bash
# List your active pushes (requires authentication)
pwpush list
# List expired pushes
pwpush list --expired
# View audit log for a specific push
pwpush audit <url_token>
# Expire a push immediately
pwpush expire <url_token>
```
### Configuration
```bash
# View current configuration
pwpush config show
# Set default expiration settings
pwpush config set --key expire_after_days --value 7
pwpush config set --key expire_after_views --value 10
# Enable JSON output by default
pwpush config set --key json --value true
# Logout and clear credentials
pwpush logout
```
## Advanced Usage
### Push Types
The `--kind` parameter allows you to specify the type of content being pushed:
```bash
# Text/Password (default)
pwpush push --secret "mypassword" --kind text
# URL - for sharing links that will be displayed as clickable URLs
pwpush push --secret "https://example.com" --kind url
# QR Code - for content that will be displayed as a QR code
pwpush push --secret "QR data content" --kind qr
# File - automatically set when using push-file command
pwpush push-file document.pdf # kind is automatically set to "file"
```
### JSON Output
```bash
# Get JSON output for scripting
pwpush --json push --secret "password"
pwpush --json list
```
### Verbose and Debug Modes
```bash
# Enable verbose output
pwpush --verbose push --secret "password"
# Enable debug mode for troubleshooting
pwpush --debug push --secret "password"
```
### Batch Operations
```bash
# Generate and distribute multiple passwords
for i in {1..5}; do
pwpush --json push --auto --note "Batch password $i"
done
```
## Configuration Reference
### Instance Settings
| Key | Description | Example |
|-----|-------------|---------|
| `url` | Password Pusher instance URL | `https://eu.pwpush.com` |
| `email` | Your account email | `user@example.com` |
| `token` | Your API token | `abc123...` |
### Expiration Settings
| Key | Description | Valid Values |
|-----|-------------|--------------|
| `expire_after_days` | Default days until expiration | 1-90 |
| `expire_after_views` | Default views until expiration | 1-100 |
| `retrieval_step` | Require click-through for retrieval | true/false |
| `deletable_by_viewer` | Allow viewers to delete content | true/false |
### CLI Settings
| Key | Description | Valid Values |
|-----|-------------|--------------|
| `json` | Output in JSON format | true/false |
| `verbose` | Enable verbose output | true/false |
## Examples
### Developer Workflow
```bash
# Push database credentials with team
pwpush push --secret "db_password_123" --days 1 --views 3 --note "Staging DB - expires in 24h"
# Push API keys securely
pwpush push --secret "sk_live_..." --days 7 --views 1 --note "Production API Key"
# Share deployment URLs as clickable links
pwpush push --secret "https://staging.example.com/deploy" --kind url --days 1 --views 5
```
### System Administration
```bash
# Push temporary access credentials
pwpush push --auto --days 1 --views 1 --note "Emergency access - $(date)"
# Push configuration files
pwpush push-file /etc/nginx/nginx.conf --days 3 --views 5
```
### Team Collaboration
```bash
# Push deployment secrets
pwpush push --secret "deploy_token" --days 1 --views 10 --note "Release v2.1.0"
# Push sensitive documents
pwpush push-file sensitive_document.pdf --days 7 --views 3 --retrieval-step
```
## Troubleshooting
### Common Issues
**Connection Errors**
```bash
# Check your instance URL
pwpush config show
# Test connectivity
pwpush --debug push --secret "test"
```
**Authentication Issues**
```bash
# Verify your credentials
pwpush config show
# Re-login
pwpush logout
pwpush login
```
**Permission Errors**
```bash
# Check file permissions when uploading files
ls -la your_file.txt
pwpush push-file your_file.txt
```
### Getting Help
```bash
# View all available commands
pwpush --help
# Get help for specific commands
pwpush push --help
pwpush config --help
```
## Security Notes
- Passwords and secrets are encrypted before transmission
- All communication uses HTTPS
- Content is automatically deleted after expiration
- API tokens should be kept secure and not shared
- Use `--retrieval-step` to prevent URL scanners from consuming views
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- **Password Pusher**: https://pwpush.com
- **Documentation**: https://docs.pwpush.com
- **GitHub Repository**: https://github.com/pglombardo/pwpush-cli
- **Open Source Project**: https://github.com/pglombardo/PasswordPusher
## About Apnotic
This CLI tool is built by **Apnotic**.
- **Company Homepage**: https://apnotic.com
- **Password Pusher Pro**: https://pwpush.com
Raw data
{
"_id": null,
"home_page": "https://github.com/pglombardo/pwpush",
"name": "pwpush",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9.2",
"maintainer_email": null,
"keywords": "security, cli, password, distribution, sharing, secure",
"author": "pwpush",
"author_email": "pglombardo@hey.com",
"download_url": "https://files.pythonhosted.org/packages/f1/f8/bd42beead3762f4241b92bca4feed2d7ea384e135e5b298dba77d9f7159f/pwpush-0.12.0.tar.gz",
"platform": null,
"description": "# pwpush CLI\n\n<div align=\"center\">\n\n[](https://github.com/pglombardo/pwpush-cli/actions?query=workflow%3Abuild)\n[](https://pypi.org/project/pwpush/)\n[](https://github.com/pglombardo/pwpush-cli/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot)\n\n[](https://github.com/psf/black)\n[](https://github.com/PyCQA/bandit)\n[](https://github.com/pglombardo/pwpush-cli/blob/master/.pre-commit-config.yaml)\n[](https://github.com/pglombardo/pwpush-cli/releases)\n[](https://github.com/pglombardo/pwpush/blob/master/LICENSE)\n\n**Command Line Interface for Password Pusher**\n<br>\nSecure information distribution with automatic expiration controls.\n\n</div>\n\n## Overview\n\nThe `pwpush` CLI is a powerful command-line tool that interfaces with [Password Pusher](https://pwpush.com) instances for secure information distribution. It supports both the hosted services (eu.pwpush.com, us.pwpush.com) and self-hosted instances.\n\n### Why Secure Information Distribution?\n\nTraditional communication tools create permanent digital footprints that can be exploited years later. Password Pusher sidesteps this by creating:\n\n- **Self-destructing shareable links** that auto-expire after a preset number of views\n- **Time-based expiration** that automatically deletes content after a set duration \n- **Zero permanent storage** - once expired, the information is completely removed\n- **Full audit trails** so you know exactly who accessed what and when\n\n### Key Features\n\n- \ud83d\udd10 **Secure Information Distribution**: Self-destructing links for passwords, secrets, and files with automatic expiration and complete audit trails.\n- \ud83c\udf10 **Multi-Instance Support**: Works with eu.pwpush.com, us.pwpush.com, or your own instance\n- \ud83d\udd11 **Authentication**: Full API integration with user accounts\n- \ud83d\udcca **Audit Logs**: Track access and usage of distributed content\n- \ud83c\udfaf **Flexible Expiration**: Set expiration by views, days, or both\n- \ud83d\udcc1 **File Support**: Distribute files securely with the same expiration controls and audit logs\n- \ud83c\udfa8 **Rich Output**: Beautiful terminal output with tables and formatting\n\n## Installation\n\n```bash\npip install pwpush\n```\n\n**Requirements**: Python 3.9.2 or higher\n\n## Quick Start\n\n### 1. Basic Usage (Anonymous)\n\n```bash\n# Push a password (interactive mode)\npwpush push\n\n# Push a password directly\npwpush push --secret \"mypassword123\"\n\n# Auto-generate a secure password\npwpush push --auto\n\n# Push with custom expiration (7 days, 5 views)\npwpush push --secret \"mypassword\" --days 7 --views 5\n```\n\n### 2. Configure Your Instance\n\nThe CLI works with multiple Password Pusher instances:\n\n```bash\n# Use the EU instance\npwpush config set --key url --value https://eu.pwpush.com\n\n# Use the US instance \npwpush config set --key url --value https://us.pwpush.com\n\n# Use your own self-hosted instance\npwpush config set --key url --value https://pwpush.yourdomain.com\n```\n\n### 3. Authentication (Optional)\n\nFor advanced features like listing pushes and audit logs, authenticate with your account:\n\n```bash\n# Login with your credentials\npwpush login\n\n# Or set credentials manually\npwpush config set --key email --value your@email.com\npwpush config set --key token --value your_api_token\n```\n\nGet your API token from: https://pwpush.com/en/users/token\n\n## Common Commands\n\n### Pushing Content\n\n```bash\n# Push a password with custom settings\npwpush push --secret \"password123\" --days 3 --views 10 --deletable\n\n# Push as URL (for sharing links)\npwpush push --secret \"https://example.com\" --kind url\n\n# Push as QR code\npwpush push --secret \"QR data content\" --kind qr\n\n# Push a file\npwpush push-file document.pdf --days 7 --views 5\n\n# Push with a reference note (requires authentication)\npwpush push --secret \"password\" --note \"Employee onboarding - John Doe\"\n\n# Require click-through for retrieval (prevents URL scanners)\npwpush push --secret \"password\" --retrieval-step\n```\n\n### Managing Pushes\n\n```bash\n# List your active pushes (requires authentication)\npwpush list\n\n# List expired pushes\npwpush list --expired\n\n# View audit log for a specific push\npwpush audit <url_token>\n\n# Expire a push immediately\npwpush expire <url_token>\n```\n\n### Configuration\n\n```bash\n# View current configuration\npwpush config show\n\n# Set default expiration settings\npwpush config set --key expire_after_days --value 7\npwpush config set --key expire_after_views --value 10\n\n# Enable JSON output by default\npwpush config set --key json --value true\n\n# Logout and clear credentials\npwpush logout\n```\n\n## Advanced Usage\n\n### Push Types\n\nThe `--kind` parameter allows you to specify the type of content being pushed:\n\n```bash\n# Text/Password (default)\npwpush push --secret \"mypassword\" --kind text\n\n# URL - for sharing links that will be displayed as clickable URLs\npwpush push --secret \"https://example.com\" --kind url\n\n# QR Code - for content that will be displayed as a QR code\npwpush push --secret \"QR data content\" --kind qr\n\n# File - automatically set when using push-file command\npwpush push-file document.pdf # kind is automatically set to \"file\"\n```\n\n### JSON Output\n\n```bash\n# Get JSON output for scripting\npwpush --json push --secret \"password\"\npwpush --json list\n```\n\n### Verbose and Debug Modes\n\n```bash\n# Enable verbose output\npwpush --verbose push --secret \"password\"\n\n# Enable debug mode for troubleshooting\npwpush --debug push --secret \"password\"\n```\n\n### Batch Operations\n\n```bash\n# Generate and distribute multiple passwords\nfor i in {1..5}; do\n pwpush --json push --auto --note \"Batch password $i\"\ndone\n```\n\n## Configuration Reference\n\n### Instance Settings\n\n| Key | Description | Example |\n|-----|-------------|---------|\n| `url` | Password Pusher instance URL | `https://eu.pwpush.com` |\n| `email` | Your account email | `user@example.com` |\n| `token` | Your API token | `abc123...` |\n\n### Expiration Settings\n\n| Key | Description | Valid Values |\n|-----|-------------|--------------|\n| `expire_after_days` | Default days until expiration | 1-90 |\n| `expire_after_views` | Default views until expiration | 1-100 |\n| `retrieval_step` | Require click-through for retrieval | true/false |\n| `deletable_by_viewer` | Allow viewers to delete content | true/false |\n\n### CLI Settings\n\n| Key | Description | Valid Values |\n|-----|-------------|--------------|\n| `json` | Output in JSON format | true/false |\n| `verbose` | Enable verbose output | true/false |\n\n## Examples\n\n### Developer Workflow\n\n```bash\n# Push database credentials with team\npwpush push --secret \"db_password_123\" --days 1 --views 3 --note \"Staging DB - expires in 24h\"\n\n# Push API keys securely\npwpush push --secret \"sk_live_...\" --days 7 --views 1 --note \"Production API Key\"\n\n# Share deployment URLs as clickable links\npwpush push --secret \"https://staging.example.com/deploy\" --kind url --days 1 --views 5\n```\n\n### System Administration\n\n```bash\n# Push temporary access credentials\npwpush push --auto --days 1 --views 1 --note \"Emergency access - $(date)\"\n\n# Push configuration files\npwpush push-file /etc/nginx/nginx.conf --days 3 --views 5\n```\n\n### Team Collaboration\n\n```bash\n# Push deployment secrets\npwpush push --secret \"deploy_token\" --days 1 --views 10 --note \"Release v2.1.0\"\n\n# Push sensitive documents\npwpush push-file sensitive_document.pdf --days 7 --views 3 --retrieval-step\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Connection Errors**\n```bash\n# Check your instance URL\npwpush config show\n\n# Test connectivity\npwpush --debug push --secret \"test\"\n```\n\n**Authentication Issues**\n```bash\n# Verify your credentials\npwpush config show\n\n# Re-login\npwpush logout\npwpush login\n```\n\n**Permission Errors**\n```bash\n# Check file permissions when uploading files\nls -la your_file.txt\npwpush push-file your_file.txt\n```\n\n### Getting Help\n\n```bash\n# View all available commands\npwpush --help\n\n# Get help for specific commands\npwpush push --help\npwpush config --help\n```\n\n## Security Notes\n\n- Passwords and secrets are encrypted before transmission\n- All communication uses HTTPS\n- Content is automatically deleted after expiration\n- API tokens should be kept secure and not shared\n- Use `--retrieval-step` to prevent URL scanners from consuming views\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Links\n\n- **Password Pusher**: https://pwpush.com\n- **Documentation**: https://docs.pwpush.com\n- **GitHub Repository**: https://github.com/pglombardo/pwpush-cli\n- **Open Source Project**: https://github.com/pglombardo/PasswordPusher\n\n## About Apnotic\n\nThis CLI tool is built by **Apnotic**.\n\n- **Company Homepage**: https://apnotic.com\n- **Password Pusher Pro**: https://pwpush.com\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Command Line Interface to Password Pusher - secure information distribution with automatic expiration controls.",
"version": "0.12.0",
"project_urls": {
"Homepage": "https://github.com/pglombardo/pwpush",
"Repository": "https://github.com/pglombardo/pwpush"
},
"split_keywords": [
"security",
" cli",
" password",
" distribution",
" sharing",
" secure"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ce4992b1590f78bcf623affb4ff17773cdf0813c1a83cc961fbaae38c614b893",
"md5": "e8c5fad3a215f9f37206f434965b07ba",
"sha256": "0352939f46df89305b150e6b95dad4a503d8011912e3eac40af0f34624bed681"
},
"downloads": -1,
"filename": "pwpush-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e8c5fad3a215f9f37206f434965b07ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9.2",
"size": 14724,
"upload_time": "2025-10-06T11:25:20",
"upload_time_iso_8601": "2025-10-06T11:25:20.445272Z",
"url": "https://files.pythonhosted.org/packages/ce/49/92b1590f78bcf623affb4ff17773cdf0813c1a83cc961fbaae38c614b893/pwpush-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f1f8bd42beead3762f4241b92bca4feed2d7ea384e135e5b298dba77d9f7159f",
"md5": "5198a9abf05f3f4b6487b353cdec1eed",
"sha256": "8224eacc82fd22a8b5bda7ceae36f364e3b2173f1f04a119013280fd9f657efd"
},
"downloads": -1,
"filename": "pwpush-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "5198a9abf05f3f4b6487b353cdec1eed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9.2",
"size": 16125,
"upload_time": "2025-10-06T11:25:21",
"upload_time_iso_8601": "2025-10-06T11:25:21.724507Z",
"url": "https://files.pythonhosted.org/packages/f1/f8/bd42beead3762f4241b92bca4feed2d7ea384e135e5b298dba77d9f7159f/pwpush-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 11:25:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pglombardo",
"github_project": "pwpush",
"github_not_found": true,
"lcname": "pwpush"
}
JSON
