# Recommended: install globally with pipx
pipx install passkey-mcp

# Or with pip
pip install passkey-mcp

# Development mode (from source)
pip install -e .

# First run — guided onboarding
passkey
#  ┌─────────────────────────────────────────────┐
#  │           Welcome to passkey                 │
#  │  Secrets in your keychain. Not in config.    │
#  └─────────────────────────────────────────────┘
#  Create your first entry now? [Y/n]

# Create an entry
passkey new
# Entry name: github
# Field name: GITHUB_TOKEN
# Value: [hidden input]

# List all entries
passkey list

# Run a command with secrets injected
passkey run github -- python app.py

# Zsh (macOS default)
eval "$(passkey completion --zsh)"

# Bash
eval "$(passkey completion --bash)"

# Fish
passkey completion --fish > ~/.config/fish/completions/passkey.fish

passkey <TAB>         # Show entries + subcommands
passkey hugg<TAB>     # Fuzzy-match: huggingface_key
passkey get <TAB>     # Complete entry names
passkey run <TAB>     # Pick entries to load

$ passkey get
? Select entry to browse: (Use arrow keys, type to filter)
❯ github
  openai
  slack
  myapi_read
  myapi_write

# Type to filter:
$ passkey get my
# Automatically shows: myapi_read, myapi_write

# Single match auto-selects:
$ passkey get github
Copied 'GITHUB_TOKEN' to clipboard (auto-clears in 30s)

# Shortcut: passkey <entry> opens the picker directly
$ passkey github

# Run with secrets from one entry
passkey run github -- python app.py

# Run with secrets from multiple entries (later entries override)
passkey run aws github -- python deploy.py

# Secrets injected as env vars
passkey run myapi -- curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com/v1/data

# Scan configs and migrate plaintext secrets to keychain
passkey init                    # Auto-detect all tools
passkey init --tool claude      # Specific tool
passkey init --tool vscode

# Restore wrapped configs back to inline commands (the way out)
passkey unwrap                  # Auto-detect all tools
passkey unwrap --dry-run        # Preview first

# Add or update credentials for an MCP server
passkey add my-server                            # Interactive field entry
passkey add my-server --tool claude              # Target a specific tool config
passkey add my-server API_KEY=abc TOKEN=xyz      # Non-interactive (KEY=VALUE)

# Show security status across all tools
passkey status

# Run diagnostics
passkey doctor

# List MCP servers across tools
passkey servers

# Export all entries to file (owner-only permissions set automatically)
passkey export backup.json

# Export specific entries
passkey export backup.json --entries github openai

# Export metadata only (no secret values)
passkey export backup.json --no-secrets

# Encrypted export (AES-256-GCM + scrypt)
passkey export backup.passkey.enc --encrypt

# Import from passkey backup
passkey import backup.json

# Preview without importing
passkey import backup.json --dry-run

# Handle duplicates: skip (default), overwrite, merge
passkey import backup.json --mode merge

# Import from encrypted bundle
passkey import backup.passkey.enc --decrypt

# Import from Chrome password export (CSV)
passkey import passwords.csv --filter github.com

# Import from an existing MCP config file
passkey import claude_desktop_config.json

passkey audit              # View recent operations
passkey audit --limit 50   # Show more entries
passkey audit --clear      # Clear the log
passkey audit --summary    # Aggregate statistics

# Exit non-zero if any required fields are missing
passkey check github GITHUB_TOKEN GITHUB_USERNAME

# Generate a 32-char random secret (default)
passkey generate

# Generate with custom length
passkey generate --length 64

# Generate without auto-copying to clipboard
passkey generate --no-copy

# List built-in templates
passkey template list

# Show a template's fields
passkey template show github

# Apply a template to create a new entry
passkey template apply github

# Save a custom template from an existing entry
passkey template add my-service --from myapi

# Share an entry (generates encrypted file + passphrase)
passkey share github --output github-shared.passkey

# Receive a shared entry
passkey receive github-shared.passkey

# Mark an entry as rotated (updates last_rotated timestamp)
passkey rotate github

# Run expanded diagnostics
passkey doctor --deep

passkey config require-auth on

passkey unwrap                      # all detected tools
passkey unwrap --tool claude        # one tool
passkey unwrap --server github      # one server
passkey unwrap --restore-secrets    # also write secret values back into the config
passkey unwrap --dry-run            # preview only

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "github.server"],
      "env": {
        "GITHUB_TOKEN": "ghp_PLAINTEXT_SECRET_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "github": {
      "command": "passkey",
      "args": ["run", "github", "--", "python", "-m", "github.server"]
    }
  }
}

{
  "mcpServers": {
    "passkey": {
      "command": "passkey-mcp-server"
    }
  }
}

sudo sed -i '' '2i\
auth       sufficient     pam_tid.so
' /etc/pam.d/sudo

export PYTHON_KEYRING_BACKEND=keyring.backends.SecretService.Keyring
# or for headless environments:
export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring

passkey list   # check exact names (case-sensitive)

passkey import backup.json --mode merge

pip install -e ".[dev]"
pytest tests/ -v
ruff check passkey/