# Zap CLI
> CLI companion for Zap credential manager - inject secrets from development sessions as environment variables.
## What is Zap CLI?
Zap CLI works with the [Zap Desktop App](https://github.com/hunter-arton/zap) to inject your API keys, tokens, and secrets directly into your development environment - no more `.env` files cluttering your projects!
---
## 📦 Installation
### Prerequisites
- **Python 3.8 or higher** required
- **Zap Desktop App** (to create sessions)
Check if you have Python:
```bash
python3 --version
```
If not installed, download from: https://www.python.org/downloads/
---
### Step 1: Install Zap CLI
#### **macOS & Linux:**
```bash
pip3 install zapc
```
#### **Windows:**
```bash
pip install zapc
```
---
### Step 2: Set Up PATH (macOS/Linux Only)
After installation, you may see a warning like:
```
WARNING: The script zap is installed in '/Users/yourname/Library/Python/3.x/bin' which is not on PATH.
```
**This is normal!** You need to add Python's bin directory to your PATH.
#### **For macOS (zsh - default on new Macs):**
```bash
# Add to PATH
echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.zshrc
# Reload your shell
source ~/.zshrc
```
**Note:** Replace `3.9` with your Python version if different. Check with `python3 --version`
#### **For macOS (bash - older Macs):**
```bash
# Add to PATH
echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.bash_profile
# Reload your shell
source ~/.bash_profile
```
#### **For Linux:**
```bash
# Add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# Reload your shell
source ~/.bashrc
```
#### **For Windows:**
Windows usually adds to PATH automatically. If `zap` doesn't work:
1. Search for "Environment Variables" in Start Menu
2. Click "Environment Variables"
3. Under "User variables", find "Path"
4. Click "Edit"
5. Click "New"
6. Add: `C:\Users\YourName\AppData\Roaming\Python\Python3x\Scripts`
7. Click "OK" on all dialogs
8. Restart your terminal
---
### Step 3: Verify Installation
```bash
zap --version
```
**Expected output:** `0.1.0`
If you see the version number, **you're all set!** ✅
If you get `command not found`, see [Troubleshooting](#troubleshooting) below.
---
## 🚀 Quick Start
### 1. Create a Session (Desktop App)
First, open the Zap desktop app and create a development session:
1. Open **Zap Desktop App**
2. Go to **Dev Mode**
3. Select a box with your secrets
4. Click **"Create Session"**
5. Give it a name (e.g., `my-project-dev`)
The desktop app creates a session file that the CLI can read.
### 2. List Available Sessions
```bash
zap list
```
You should see your sessions from the desktop app!
### 3. Set Session for Your Project
Navigate to your project directory:
```bash
cd ~/my-awesome-project
zap use my-project-dev
```
This creates a `zap.json` file in your project.
### 4. Run Commands with Secrets
```bash
# Your secrets are automatically injected as environment variables!
zap run -- npm start
zap run -- python app.py
zap run -- cargo run
zap run -- go run main.go
```
**That's it!** Your secrets are now available as environment variables.
---
## 📖 Commands
### `zap start`
Opens the Zap desktop app.
```bash
zap start
```
### `zap list [SESSION_NAME]`
Lists all available sessions or secrets in a specific session.
```bash
# List all sessions
zap list
# List secrets in a specific session
zap list my-project-dev
```
### `zap use <SESSION_NAME>`
Sets the current session for your project.
```bash
zap use my-project-dev
```
Creates a `zap.json` file in the current directory.
### `zap run -- <COMMAND>`
Runs a command with secrets injected as environment variables.
```bash
# Basic usage
zap run -- npm start
# With specific session (override current)
zap run --session other-session -- python app.py
# Show loaded environment variables (verbose)
zap run -v -- npm test
# Add prefix to environment variable names
zap run --prefix MY_APP -- npm start
```
**Options:**
- `--session, -s`: Override current session
- `--verbose, -v`: Show loaded environment variables
- `--prefix, -p`: Add prefix to env var names
### `zap status`
Shows the current session status for your project.
```bash
zap status
```
### `zap stop <SESSION_NAME>`
Stops a specific session (deletes the session file).
```bash
zap stop my-project-dev
```
### `zap clear`
Clears all active sessions.
```bash
zap clear
```
**Warning:** This deletes all session files!
---
## 🔧 How It Works
### Session Files
When you create a session in the desktop app, it writes an encrypted JSON file to:
- **macOS**: `~/Library/Application Support/com.devtool.zap/sessions/`
- **Windows**: `%APPDATA%/com.devtool.zap/sessions/`
- **Linux**: `~/.config/com.devtool.zap/sessions/`
The CLI reads these files and decrypts your secrets.
### Environment Variable Naming
Secret names are converted to UPPERCASE environment variables:
| Secret Name | Environment Variable |
|-------------|---------------------|
| `Database Password` | `DATABASE_PASSWORD` |
| `api-key` | `API_KEY` |
| `my.secret.value` | `MY_SECRET_VALUE` |
| `AWS_ACCESS_KEY` | `AWS_ACCESS_KEY` |
### Project Context
When you run `zap use <session>`, a `zap.json` file is created:
```json
{
"app": "zap",
"current_session": "my-project-dev",
"available_secrets": [
"DATABASE_URL",
"API_KEY",
"AWS_SECRET"
]
}
```
**Add `zap.json` to your `.gitignore`!**
---
## 💡 Example Workflows
### Web Development
```bash
cd my-web-app/
zap use web-dev-session
# Start dev server with secrets
zap run -- npm run dev
# Run tests with secrets
zap run -- npm test
# Build with secrets
zap run -- npm run build
```
### Python Development
```bash
cd my-python-app/
zap use python-dev
# Run app
zap run -- python app.py
# Run with uvicorn
zap run -- uvicorn main:app --reload
# Run Django
zap run -- python manage.py runserver
```
### Multi-Environment
```bash
# Development
zap use dev-session
zap run -- npm start
# Staging
zap use staging-session
zap run -- npm start
# Check current environment
zap status
```
---
## 🔒 Security
- ✅ Secrets are encrypted with AES-GCM (256-bit)
- ✅ Session keys are unique per session
- ✅ No secrets stored in plaintext
- ✅ Environment variables only exist during command execution
- ✅ No network required - everything is local
**Never commit:**
- `zap.json` (project context file)
- Session files (they're in system directories anyway)
---
## 🐛 Troubleshooting
### `zap: command not found`
**Problem:** Python's bin directory is not in your PATH.
**Solution:**
1. Find where `zap` was installed:
```bash
pip3 show zapc
```
Look for the "Location" line.
2. Add the bin directory to PATH (see [Step 2](#step-2-set-up-path-macoslinux-only) above)
3. Or use the full path:
```bash
# Find it
which python3
# Usually at: /Users/yourname/Library/Python/3.x/bin/zap
# Use full path
/Users/yourname/Library/Python/3.x/bin/zap --version
```
### `No active sessions found`
**Problem:** No sessions created in desktop app.
**Solution:**
1. Open Zap Desktop App
2. Go to Dev Mode
3. Create a session from a box
4. Try `zap list` again
### `Session 'xxx' not found`
**Problem:** Session was deleted in desktop app or doesn't exist.
**Solution:**
```bash
# List available sessions
zap list
# Use an existing session
zap use <session-from-list>
```
### `No current session set`
**Problem:** No `zap.json` in current directory.
**Solution:**
```bash
# Set a session first
zap use my-session
# Or specify session when running
zap run --session my-session -- npm start
```
### Permission Errors
**Problem:** Can't write `zap.json` file.
**Solution:**
```bash
# Check directory permissions
ls -la
# Make sure you have write permissions in current directory
```
---
## 🆚 Alternative: Using pipx (Recommended for Isolation)
[pipx](https://pypa.github.io/pipx/) installs CLI tools in isolated environments and handles PATH automatically.
### Install pipx:
```bash
# macOS
brew install pipx
pipx ensurepath
# Linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath
# Windows
python -m pip install --user pipx
python -m pipx ensurepath
```
### Install Zap CLI with pipx:
```bash
pipx install zapc
```
**No PATH configuration needed!** ✅
---
## 📚 Additional Resources
- **Desktop App**: [github.com/hunter-arton/zap](https://github.com/hunter-arton/zap)
- **Issues**: [github.com/hunter-arton/zap/issues](https://github.com/hunter-arton/zap/issues)
- **PyPI**: [pypi.org/project/zapc](https://pypi.org/project/zapc)
---
## ⚡ Quick Reference
```bash
# Installation
pip3 install zapc
# Setup (macOS/Linux)
echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Verify
zap --version
# Basic usage
zap list # List sessions
zap use my-session # Set session
zap run -- npm start # Run with secrets
zap status # Check current session
```
---
## 🤝 Support
Having issues? Check:
1. Python version: `python3 --version` (need 3.8+)
2. Installation: `pip3 show zapc`
3. PATH setup: `echo $PATH`
4. Desktop app is running and has sessions
Still stuck? [Open an issue](https://github.com/hunter-arton/zap/issues)!
---
## 📄 License
MIT License - see [LICENSE](../LICENSE) file for details.
---
**Made with ❤️ for developers who care about security**
Raw data
{
"_id": null,
"home_page": "https://github.com/hunter-arton/zap",
"name": "zapc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "credentials, secrets, environment, variables, development",
"author": "Hunter Arton",
"author_email": "Arton Hunter <arton.hunter@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7b/67/1a9accfd2ddfba274e81b83b7ccf4ff2041e23843fe8bc05f6a45fd3f29d/zapc-0.1.1.tar.gz",
"platform": null,
"description": "# Zap CLI\n\n> CLI companion for Zap credential manager - inject secrets from development sessions as environment variables.\n\n## What is Zap CLI?\n\nZap CLI works with the [Zap Desktop App](https://github.com/hunter-arton/zap) to inject your API keys, tokens, and secrets directly into your development environment - no more `.env` files cluttering your projects!\n\n---\n\n## \ud83d\udce6 Installation\n\n### Prerequisites\n\n- **Python 3.8 or higher** required\n- **Zap Desktop App** (to create sessions)\n\nCheck if you have Python:\n```bash\npython3 --version\n```\n\nIf not installed, download from: https://www.python.org/downloads/\n\n---\n\n### Step 1: Install Zap CLI\n\n#### **macOS & Linux:**\n```bash\npip3 install zapc\n```\n\n#### **Windows:**\n```bash\npip install zapc\n```\n\n---\n\n### Step 2: Set Up PATH (macOS/Linux Only)\n\nAfter installation, you may see a warning like:\n```\nWARNING: The script zap is installed in '/Users/yourname/Library/Python/3.x/bin' which is not on PATH.\n```\n\n**This is normal!** You need to add Python's bin directory to your PATH.\n\n#### **For macOS (zsh - default on new Macs):**\n\n```bash\n# Add to PATH\necho 'export PATH=\"$HOME/Library/Python/3.9/bin:$PATH\"' >> ~/.zshrc\n\n# Reload your shell\nsource ~/.zshrc\n```\n\n**Note:** Replace `3.9` with your Python version if different. Check with `python3 --version`\n\n#### **For macOS (bash - older Macs):**\n\n```bash\n# Add to PATH\necho 'export PATH=\"$HOME/Library/Python/3.9/bin:$PATH\"' >> ~/.bash_profile\n\n# Reload your shell\nsource ~/.bash_profile\n```\n\n#### **For Linux:**\n\n```bash\n# Add to PATH\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc\n\n# Reload your shell\nsource ~/.bashrc\n```\n\n#### **For Windows:**\n\nWindows usually adds to PATH automatically. If `zap` doesn't work:\n\n1. Search for \"Environment Variables\" in Start Menu\n2. Click \"Environment Variables\"\n3. Under \"User variables\", find \"Path\"\n4. Click \"Edit\"\n5. Click \"New\"\n6. Add: `C:\\Users\\YourName\\AppData\\Roaming\\Python\\Python3x\\Scripts`\n7. Click \"OK\" on all dialogs\n8. Restart your terminal\n\n---\n\n### Step 3: Verify Installation\n\n```bash\nzap --version\n```\n\n**Expected output:** `0.1.0`\n\nIf you see the version number, **you're all set!** \u2705\n\nIf you get `command not found`, see [Troubleshooting](#troubleshooting) below.\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### 1. Create a Session (Desktop App)\n\nFirst, open the Zap desktop app and create a development session:\n\n1. Open **Zap Desktop App**\n2. Go to **Dev Mode**\n3. Select a box with your secrets\n4. Click **\"Create Session\"**\n5. Give it a name (e.g., `my-project-dev`)\n\nThe desktop app creates a session file that the CLI can read.\n\n### 2. List Available Sessions\n\n```bash\nzap list\n```\n\nYou should see your sessions from the desktop app!\n\n### 3. Set Session for Your Project\n\nNavigate to your project directory:\n\n```bash\ncd ~/my-awesome-project\nzap use my-project-dev\n```\n\nThis creates a `zap.json` file in your project.\n\n### 4. Run Commands with Secrets\n\n```bash\n# Your secrets are automatically injected as environment variables!\nzap run -- npm start\nzap run -- python app.py\nzap run -- cargo run\nzap run -- go run main.go\n```\n\n**That's it!** Your secrets are now available as environment variables.\n\n---\n\n## \ud83d\udcd6 Commands\n\n### `zap start`\nOpens the Zap desktop app.\n\n```bash\nzap start\n```\n\n### `zap list [SESSION_NAME]`\nLists all available sessions or secrets in a specific session.\n\n```bash\n# List all sessions\nzap list\n\n# List secrets in a specific session\nzap list my-project-dev\n```\n\n### `zap use <SESSION_NAME>`\nSets the current session for your project.\n\n```bash\nzap use my-project-dev\n```\n\nCreates a `zap.json` file in the current directory.\n\n### `zap run -- <COMMAND>`\nRuns a command with secrets injected as environment variables.\n\n```bash\n# Basic usage\nzap run -- npm start\n\n# With specific session (override current)\nzap run --session other-session -- python app.py\n\n# Show loaded environment variables (verbose)\nzap run -v -- npm test\n\n# Add prefix to environment variable names\nzap run --prefix MY_APP -- npm start\n```\n\n**Options:**\n- `--session, -s`: Override current session\n- `--verbose, -v`: Show loaded environment variables\n- `--prefix, -p`: Add prefix to env var names\n\n### `zap status`\nShows the current session status for your project.\n\n```bash\nzap status\n```\n\n### `zap stop <SESSION_NAME>`\nStops a specific session (deletes the session file).\n\n```bash\nzap stop my-project-dev\n```\n\n### `zap clear`\nClears all active sessions.\n\n```bash\nzap clear\n```\n\n**Warning:** This deletes all session files!\n\n---\n\n## \ud83d\udd27 How It Works\n\n### Session Files\n\nWhen you create a session in the desktop app, it writes an encrypted JSON file to:\n\n- **macOS**: `~/Library/Application Support/com.devtool.zap/sessions/`\n- **Windows**: `%APPDATA%/com.devtool.zap/sessions/`\n- **Linux**: `~/.config/com.devtool.zap/sessions/`\n\nThe CLI reads these files and decrypts your secrets.\n\n### Environment Variable Naming\n\nSecret names are converted to UPPERCASE environment variables:\n\n| Secret Name | Environment Variable |\n|-------------|---------------------|\n| `Database Password` | `DATABASE_PASSWORD` |\n| `api-key` | `API_KEY` |\n| `my.secret.value` | `MY_SECRET_VALUE` |\n| `AWS_ACCESS_KEY` | `AWS_ACCESS_KEY` |\n\n### Project Context\n\nWhen you run `zap use <session>`, a `zap.json` file is created:\n\n```json\n{\n \"app\": \"zap\",\n \"current_session\": \"my-project-dev\",\n \"available_secrets\": [\n \"DATABASE_URL\",\n \"API_KEY\",\n \"AWS_SECRET\"\n ]\n}\n```\n\n**Add `zap.json` to your `.gitignore`!**\n\n---\n\n## \ud83d\udca1 Example Workflows\n\n### Web Development\n\n```bash\ncd my-web-app/\nzap use web-dev-session\n\n# Start dev server with secrets\nzap run -- npm run dev\n\n# Run tests with secrets\nzap run -- npm test\n\n# Build with secrets\nzap run -- npm run build\n```\n\n### Python Development\n\n```bash\ncd my-python-app/\nzap use python-dev\n\n# Run app\nzap run -- python app.py\n\n# Run with uvicorn\nzap run -- uvicorn main:app --reload\n\n# Run Django\nzap run -- python manage.py runserver\n```\n\n### Multi-Environment\n\n```bash\n# Development\nzap use dev-session\nzap run -- npm start\n\n# Staging\nzap use staging-session\nzap run -- npm start\n\n# Check current environment\nzap status\n```\n\n---\n\n## \ud83d\udd12 Security\n\n- \u2705 Secrets are encrypted with AES-GCM (256-bit)\n- \u2705 Session keys are unique per session\n- \u2705 No secrets stored in plaintext\n- \u2705 Environment variables only exist during command execution\n- \u2705 No network required - everything is local\n\n**Never commit:**\n- `zap.json` (project context file)\n- Session files (they're in system directories anyway)\n\n---\n\n## \ud83d\udc1b Troubleshooting\n\n### `zap: command not found`\n\n**Problem:** Python's bin directory is not in your PATH.\n\n**Solution:**\n\n1. Find where `zap` was installed:\n ```bash\n pip3 show zapc\n ```\n Look for the \"Location\" line.\n\n2. Add the bin directory to PATH (see [Step 2](#step-2-set-up-path-macoslinux-only) above)\n\n3. Or use the full path:\n ```bash\n # Find it\n which python3\n # Usually at: /Users/yourname/Library/Python/3.x/bin/zap\n \n # Use full path\n /Users/yourname/Library/Python/3.x/bin/zap --version\n ```\n\n### `No active sessions found`\n\n**Problem:** No sessions created in desktop app.\n\n**Solution:**\n1. Open Zap Desktop App\n2. Go to Dev Mode\n3. Create a session from a box\n4. Try `zap list` again\n\n### `Session 'xxx' not found`\n\n**Problem:** Session was deleted in desktop app or doesn't exist.\n\n**Solution:**\n```bash\n# List available sessions\nzap list\n\n# Use an existing session\nzap use <session-from-list>\n```\n\n### `No current session set`\n\n**Problem:** No `zap.json` in current directory.\n\n**Solution:**\n```bash\n# Set a session first\nzap use my-session\n\n# Or specify session when running\nzap run --session my-session -- npm start\n```\n\n### Permission Errors\n\n**Problem:** Can't write `zap.json` file.\n\n**Solution:**\n```bash\n# Check directory permissions\nls -la\n\n# Make sure you have write permissions in current directory\n```\n\n---\n\n## \ud83c\udd9a Alternative: Using pipx (Recommended for Isolation)\n\n[pipx](https://pypa.github.io/pipx/) installs CLI tools in isolated environments and handles PATH automatically.\n\n### Install pipx:\n\n```bash\n# macOS\nbrew install pipx\npipx ensurepath\n\n# Linux\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\n\n# Windows\npython -m pip install --user pipx\npython -m pipx ensurepath\n```\n\n### Install Zap CLI with pipx:\n\n```bash\npipx install zapc\n```\n\n**No PATH configuration needed!** \u2705\n\n---\n\n## \ud83d\udcda Additional Resources\n\n- **Desktop App**: [github.com/hunter-arton/zap](https://github.com/hunter-arton/zap)\n- **Issues**: [github.com/hunter-arton/zap/issues](https://github.com/hunter-arton/zap/issues)\n- **PyPI**: [pypi.org/project/zapc](https://pypi.org/project/zapc)\n\n---\n\n## \u26a1 Quick Reference\n\n```bash\n# Installation\npip3 install zapc\n\n# Setup (macOS/Linux)\necho 'export PATH=\"$HOME/Library/Python/3.9/bin:$PATH\"' >> ~/.zshrc\nsource ~/.zshrc\n\n# Verify\nzap --version\n\n# Basic usage\nzap list # List sessions\nzap use my-session # Set session\nzap run -- npm start # Run with secrets\nzap status # Check current session\n```\n\n---\n\n## \ud83e\udd1d Support\n\nHaving issues? Check:\n1. Python version: `python3 --version` (need 3.8+)\n2. Installation: `pip3 show zapc`\n3. PATH setup: `echo $PATH`\n4. Desktop app is running and has sessions\n\nStill stuck? [Open an issue](https://github.com/hunter-arton/zap/issues)!\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](../LICENSE) file for details.\n\n---\n\n**Made with \u2764\ufe0f for developers who care about security**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI companion for Zap credential manager - inject secrets as environment variables",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/hunter-arton/zap#readme",
"Homepage": "https://github.com/hunter-arton/zap",
"Issues": "https://github.com/hunter-arton/zap/issues",
"Repository": "https://github.com/hunter-arton/zap"
},
"split_keywords": [
"credentials",
" secrets",
" environment",
" variables",
" development"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "678eb266966401f28ba5ecf678e26319ecaebf7a4617a8345dd00f2383901d09",
"md5": "df75307717fe104be05b36c903d7aaca",
"sha256": "95bc362539a29b505c5844b1bd1ec2062cee31365e10d2246134a75ea6425362"
},
"downloads": -1,
"filename": "zapc-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df75307717fe104be05b36c903d7aaca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9352,
"upload_time": "2025-10-06T08:40:52",
"upload_time_iso_8601": "2025-10-06T08:40:52.693241Z",
"url": "https://files.pythonhosted.org/packages/67/8e/b266966401f28ba5ecf678e26319ecaebf7a4617a8345dd00f2383901d09/zapc-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7b671a9accfd2ddfba274e81b83b7ccf4ff2041e23843fe8bc05f6a45fd3f29d",
"md5": "91e5012610f1ee37dc0aae0ba888ea11",
"sha256": "3a79412e8ccca01ca8e88247cbce53ccadcbd0a4286d76751631607640d6a913"
},
"downloads": -1,
"filename": "zapc-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "91e5012610f1ee37dc0aae0ba888ea11",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13022,
"upload_time": "2025-10-06T08:40:53",
"upload_time_iso_8601": "2025-10-06T08:40:53.756403Z",
"url": "https://files.pythonhosted.org/packages/7b/67/1a9accfd2ddfba274e81b83b7ccf4ff2041e23843fe8bc05f6a45fd3f29d/zapc-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 08:40:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hunter-arton",
"github_project": "zap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zapc"
}
JSON
