psst 🤫

Because your agent doesn't need to know your secrets.

The Hall of Shame

I keep pasting API keys into Claude Code. Or just letting it cat .env. Every time I tell myself I'll stop doing that. I never do.

# "just read the .env"
cat .env

# "here, use this key"
sk-live-4wB7xK9mN2pL8qR3...

Your secrets are now:

• 📜 In the model's context window
• 📟 In your terminal history
• 📁 In that log file you forgot about
• 🎓 Training data (maybe?)
• 📸 Screenshot material for your coworker's Slack

There's a better way.

What if agents could use secrets without seeing them?

# Agent writes this:
psst STRIPE_KEY -- curl -H "Authorization: Bearer $STRIPE_KEY" https://api.stripe.com

# What the agent sees:
# ✅ Command executed successfully

# What actually ran:
# curl -H "Authorization: Bearer sk_live_abc123..." https://api.stripe.com

The secret never touches the agent's context. It's injected into the subprocess environment at runtime.

The agent orchestrates. psst handles the secrets.

For Humans

You set up psst once. Then your agent handles the rest.

Installation

npm install -g psst-cli

Setup (one-time)

# Create vault (stores encryption key in your OS keychain)
psst init

# Add your secrets
psst set STRIPE_KEY          # Interactive prompt, value hidden
psst set OPENAI_API_KEY
psst set DATABASE_URL

# Verify
psst list

That's it. Now onboard your agent:

psst onboard

This adds psst instructions to your CLAUDE.md or AGENTS.md file, teaching your agent:

• How to use psst SECRET -- command
• To ask you to add missing secrets
• To shame you if you try to paste secrets in plain text 🤫

Managing Secrets

psst set <NAME>               # Add/update secret (interactive)
psst set <NAME> --stdin       # Pipe value in (for scripts)
psst get <NAME>               # View value (debugging only)
psst list                     # List all secret names
psst rm <NAME>                # Delete secret

# Import/export
psst import .env              # Import from .env file
psst import --stdin           # Import from stdin
psst import --from-env        # Import from environment variables
psst export                   # Export to stdout (.env format)
psst export --env-file .env   # Export to file

# Vault encryption (for backups/travel)
psst lock                     # Encrypt vault at rest with password
psst unlock                   # Decrypt vault

Environments

Organize secrets by environment (dev/staging/prod):

psst init --env prod          # Create vault for "prod" environment
psst --env prod set API_KEY   # Set secret in prod
psst --env prod list          # List secrets in prod
psst --env prod API_KEY -- curl https://api.example.com

# List all environments
psst list envs

Environments are stored in ~/.psst/envs/<name>/vault.db.

You can also use the PSST_ENV environment variable:

export PSST_ENV=prod
psst list                     # Uses prod environment

Note: Existing vaults at ~/.psst/vault.db continue to work as the "default" environment.

Global Flags

All commands support:

-g, --global                  # Use global vault (~/.psst/)
--env <name>                  # Use specific environment
--tag <name>                  # Filter by tag (repeatable)
--json                        # Structured JSON output
-q, --quiet                   # Suppress output, use exit codes

Local vs Global Vaults

By default, psst creates a local vault in your project directory:

psst init                     # Creates .psst/ in current directory
psst init --env dev           # Creates .psst/envs/dev/ in current directory

For user-wide secrets, use the global vault:

psst init --global            # Creates ~/.psst/
psst --global set API_KEY     # Store in global vault
psst --global list            # List global secrets

Secret Scanning

Prevent accidentally committing secrets to git:

# Scan files for leaked secrets
psst scan                     # Scan all tracked files
psst scan --staged            # Scan only git staged files
psst scan --path ./src        # Scan specific directory

# Install pre-commit hook (runs scan automatically)
psst install-hook

The scanner checks for actual vault secret values — no regex false positives. If a secret is found:

✗ Secrets found in files:

  config.js:12
    Contains: STRIPE_KEY

Found 1 secret(s) in 1 file(s)
  Tip: Use PSST_SKIP_SCAN=1 git commit to bypass

Bypass the hook when needed:

PSST_SKIP_SCAN=1 git commit -m "message"
# or
git commit --no-verify

Secret History & Rollback

Accidentally overwritten a secret? psst keeps the last 10 versions automatically.

# View version history
psst history API_KEY

# History for API_KEY
#
# ● current (active)
# ● v2  01/15/2026 14:30
# ● v1  01/10/2026 09:15
#
# 2 previous version(s)
#   Rollback: psst rollback API_KEY --to <version>

# Restore a previous version
psst rollback API_KEY --to 1
# ✓ Rolled back API_KEY to v1

Rollback is reversible — the current value is archived before restoring, so you can always undo.

Secret Tags

Organize secrets with tags for easier management:

# Add tags when setting secrets
psst set AWS_KEY --tag aws --tag prod
psst set STRIPE_KEY --tag payments --tag prod

# Manage tags on existing secrets
psst tag DB_URL prod                  # Add tag
psst untag DB_URL dev                 # Remove tag

# List secrets filtered by tag
psst list --tag aws                   # Only aws-tagged secrets
psst list --tag prod                  # Only prod-tagged secrets

# Run commands with tagged secrets only
psst --tag aws -- aws s3 ls           # Inject only aws-tagged secrets
psst --tag prod run ./deploy.sh       # Run with only prod secrets

Tags use OR logic when filtering — psst list --tag aws --tag payments returns secrets with either tag.

For Agents

You don't read secrets. You use them.

The Simple Way

psst run <command>

This injects all vault secrets into the command's environment. You never see the values.

# Run any command with all secrets available
psst run ./deploy.sh
psst run python my_script.py
psst run docker-compose up

Specific Secrets

If you only need certain secrets:

psst <SECRET_NAME> [SECRET_NAME...] -- <command>

# Single secret
psst STRIPE_KEY -- curl -H "Authorization: Bearer $STRIPE_KEY" https://api.stripe.com

# Multiple secrets
psst AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY -- aws s3 ls

What You Get Back

• Exit code of the command
• stdout/stderr of the command (with secrets automatically redacted)
• Not the secret value

Secrets are automatically replaced with [REDACTED] in command output. Use --no-mask if you need to see the actual output for debugging.

Checking Available Secrets

psst list                     # See what's available
psst list --json              # Structured output

If a Secret is Missing

psst will automatically check environment variables as a fallback. If neither the vault nor the environment has the secret, the command will fail.

Ask the human to add it:

"I need STRIPE_KEY to call the Stripe API. Please run psst set STRIPE_KEY to add it."

How It Works

┌───────────────────────────────────────────────────────┐
│  Agent Context                                        │
│                                                       │
│  "I need to deploy the app"                           │
│  > psst run ./deploy.sh                               │
│                                                       │
│  [Command executed, exit code 0]                      │
│                                                       │
│  (Agent never sees any secret values)                 │
└───────────────────────────────────────────────────────┘
                          │
                          ▼
┌───────────────────────────────────────────────────────┐
│  psst                                                 │
│                                                       │
│  1. Retrieve encryption key from OS Keychain          │
│  2. Decrypt STRIPE_KEY from local vault               │
│  3. Inject into subprocess environment                │
│  4. Execute: curl ... (with $STRIPE_KEY expanded)     │
│  5. Return exit code to agent                         │
└───────────────────────────────────────────────────────┘

Security model:

• Secrets encrypted at rest (AES-256-GCM)
• Encryption key stored in OS Keychain (macOS Keychain, libsecret, Windows Credential Manager)
• Secrets automatically redacted in command output ([REDACTED])
• Optional vault lock with password for backups/travel
• Secrets never exposed to agent context
• Zero friction for legitimate use

CI / Headless Environments

When keychain isn't available, use the PSST_PASSWORD environment variable:

export PSST_PASSWORD="your-master-password"
psst STRIPE_KEY -- ./deploy.sh

FAQ

Q: Why not just use environment variables?

Because export STRIPE_KEY=sk_live_... puts the secret:

• In your shell history
• In your agent's context (if it ran the export)
• Visible to env and printenv

psst keeps secrets out of the agent's context entirely.

Q: Why not use a .env file?

.env files are fine for local dev, but:

• Agents can cat .env and see everything
• Easy to accidentally commit
• No encryption at rest

Q: Is this like HashiCorp Vault?

Vault is for teams and infrastructure. psst is for your laptop and your AI agent. Different tools, different problems.

Q: What if the agent runs psst get STRIPE_KEY?

It'll print the value. That's a feature for human debugging. If you're worried, don't give your agent shell access. But honestly, if an agent has shell access, it can already do much worse things.

Q: How is the encryption key stored?

In your OS keychain:

• macOS: Keychain.app (unlocked when you log in)
• Linux: libsecret / gnome-keyring
• Windows: Credential Manager

Philosophy

• Local-first: Your secrets never leave your machine. No cloud, no sync, no account.
• Agent-first: Designed for AI agents to use, not just humans.
• Zero friction: No passwords to type (keychain handles it).
• Single binary: Works everywhere Bun runs.

Development

# Install dependencies
bun install

# Run locally
bun run src/main.ts --help

# Build single binary
bun run build

License

MIT