User Manual

Secrets exist but are never observable.

Command Reference

Every command in Phantom Vault 0.1.0. Run phantom <command> --help for the full options on any of them, or phantom help for the top-level list.

Agent-safe never reveals a value

Safe for an AI agent (or any script) to call — none of these hand back a secret's plaintext.

Human-only reveals / allows plaintext — needs a TTY

These expose secret material or require a person at the keyboard. They need an interactive terminal and are never available to an AI agent.

Setup & management configuration

Administrative commands. They don't reveal values, but they change how the vault behaves.

phantom edit — the encrypted notepad

phantom edit opens your entire vault in $EDITOR as a plain KEY=VALUE list — one secret per line — so you can add, change, or delete many secrets in a single pass. When you save and close the editor, Phantom re-encrypts the whole vault. Remove a line to delete that secret; lines starting with # are comments.

~ % phantom edit
# opens $EDITOR with every secret in KEY=VALUE form:
OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_live_...
DATABASE_URL=postgres://...
# edit a line to update it, delete a line to remove that secret,
# add a line to create one, then save to re-encrypt the vault.

~ % EDITOR=nano phantom edit   # use a specific editor

---

1. Installation

Open Your Terminal

On Mac: Press Cmd + Space, type "Terminal", press Enter.
On Linux: Press Ctrl + Alt + T

Install (One Command)

~ % curl -fsSL https://phantomvault.riscent.com/install | bash

  Detecting system...
  ✓ macOS 15.3 (Apple Silicon)

  Downloading phantom + vault-mcp (0.1.0)...
  ✓ Downloaded

  Installing to /usr/local/bin ...
  ✓ Installed phantom + vault-mcp to /usr/local/bin

  🔐 Phantom Vault is ready.
  Run 'phantom init' to create your vault.

Verify It Worked

~ % phantom --version
phantom 0.1.0

---

2. Your First 5 Minutes

Step 1: Create Your Vault

~ % phantom init

  Creating new vault at ~/.phantom-vault

  Enter master password: ••••••••••••••••
  Confirm master password: ••••••••••••••••

  Vault created successfully!

  Next steps:
    phantom add <name>     Add a secret
    phantom mcp install    Enable Claude Code integration
    phantom biometric enable   Enable Touch ID unlock

With Touch ID (macOS)

~ % phantom init --biometric

  Creating new vault at ~/.phantom-vault

  Enter master password: ••••••••••••••••
  Confirm master password: ••••••••••••••••

  Enabling biometric unlock...
  Touch ID enabled for vault unlock.

  Vault created successfully!

Step 2: Add Your First Secret

~ % phantom add OPENAI_API_KEY
Enter value for OPENAI_API_KEY: ••••••••••••••••••••••••••••••••
✓ Added OPENAI_API_KEY

Step 3: Connect to Claude Code

~ % phantom mcp install

  Installing MCP server for Claude Code...
  ✓ Config written to ~/Library/Application Support/Claude/claude_desktop_config.json

  Done. Restart Claude Code, then ask:
  "What secrets do I have in my vault?"

---

3. Adding Secrets

Interactive (Secure — Value Hidden)

~ % phantom add STRIPE_SECRET_KEY
Enter value: ••••••••••••••••••••••••
✓ Added STRIPE_SECRET_KEY

From Environment

~ % export TEMP_KEY="sk_live_abc123"
~ % phantom add STRIPE_KEY --from-env TEMP_KEY
✓ Added STRIPE_KEY
~ % unset TEMP_KEY

With Expiration

~ % phantom add TEMP_TOKEN --expires 7d
Enter value: ••••••••••••
✓ Added TEMP_TOKEN (expires in 7 days)

---

4. Viewing Your Secrets

List All Secrets (Names Only)

~ % phantom list

  Namespace: default

  NAME                 CREATED      EXPIRES     ACCESS
  OPENAI_API_KEY       2 days ago   never       12 times
  STRIPE_SECRET_KEY    1 day ago    never       3 times
  DATABASE_URL         5 hours ago  never       8 times

See Last 4 Characters (Verification)

~ % phantom show STRIPE_SECRET_KEY --masked
STRIPE_SECRET_KEY: ••••••••••••xyz9

---

5. Using with AI Agents

Connect to Claude Code

~ % phantom mcp install

After restarting Claude Code, your AI gets these tools:

• vault_list — See secret names (never values)
• vault_exists — Check if a secret exists
• vault_masked — See last 4 characters
• vault_run — Run commands with secrets injected
• vault_health — Check expiring secrets
• vault_rotate — Request rotation (requires your approval)

Example: Ask Claude to Deploy

# You say:
"Deploy my app to Railway using my RAILWAY_TOKEN"

# Claude runs:
vault_run(keys: ["RAILWAY_TOKEN"], command: "railway up")

# The output sanitizer is designed to redact a leaked token as:
Deploying with token [REDACTED:RAILWAY_TOKEN]...

---

6. Running Commands

Inject Secrets as Environment Variables

~ % phantom run -s OPENAI_API_KEY -- python my_script.py
✓ Running with 1 secret injected
(your script runs with OPENAI_API_KEY in its environment)

Multiple Secrets

~ % phantom run -s DATABASE_URL -s REDIS_URL -- node server.js

---

7. Namespaces

Keep work and personal secrets separate:

~ % phantom namespace create work
~ % phantom namespace use work
~ % phantom add COMPANY_API_KEY

~ % phantom namespace use default  # switch back

---

8. Health & Rotation

Check Vault Health

~ % phantom health

  Vault Status: Healthy

  Secrets: 5 total
  Expiring soon: 1
    - TEMP_TOKEN (expires in 2 days)

  Last audit entry: 3 minutes ago
  Canary status: OK

Rotate a Secret

~ % phantom rotate STRIPE_SECRET_KEY
Enter new value: ••••••••••••••••••••••••
✓ Rotated STRIPE_SECRET_KEY (v1 → v2)
✓ Old value securely erased

---

9. Audit Log

~ % phantom audit --last 10

  TIME                  EVENT           SECRET              TOOL
  2026-02-27 14:23:01   accessed        OPENAI_API_KEY      vault_run
  2026-02-27 14:20:15   accessed        DATABASE_URL        vault_run
  2026-02-27 13:05:44   added           STRIPE_SECRET_KEY   cli
  2026-02-27 12:00:00   vault_opened    -                   cli

Every access is written to the audit log. A tamper-evident HMAC-chained log is designed and in the codebase, but not yet independently verified — treat the tamper-evidence as planned.

---

10. Canary Secrets

Honeypot secrets that alert you if something tries to use them:

~ % phantom canary create BACKUP_AWS_KEY --pattern aws-access-key
✓ Created canary BACKUP_AWS_KEY
  Looks like: AKIA••••••••••••XXXX
  ⚠ Alert will trigger if this is ever accessed

---

11. Biometric Unlock

On macOS, you can unlock your vault with Touch ID instead of typing your password every time.

Check Status

~ % phantom biometric status

  Biometric Authentication Status
  ================================

  [OK] Touch ID is available
  [OK] Biometric unlock is enabled for this vault

Enable Touch ID

~ % phantom biometric enable
  Enter master password to enable biometric: ••••••••••••

  Biometric unlock enabled!
  You can now unlock with Touch ID.

Disable Touch ID

~ % phantom biometric disable
  Biometric unlock disabled.
  You will need to use your password to unlock the vault.

---

12. Security Policies

Control which tools can access your secrets and set usage restrictions.

View Current Policy

~ % phantom policy show

  Security Policy:
  ================

  require_confirmation = ["shell_exec"]

  (Using default policy)

Create a Policy File

# my-policy.toml
allowed_tools = ["exec_sql", "http_request", "vault_run"]
blocked_tools = ["shell_exec"]
require_confirmation = ["write_file"]
rate_limit = 100  # max 100 secret accesses per hour

[time_restrictions]
enabled = true
start_hour = 9
end_hour = 18
timezone = "America/New_York"

Apply a Policy

~ % phantom policy set my-policy.toml
Security policy updated from 'my-policy.toml'

New policy:
allowed_tools = ["exec_sql", "http_request", "vault_run"]
blocked_tools = ["shell_exec"]
...

Reset to Defaults

~ % phantom policy reset
Reset security policy to defaults? [y/N]: y
Security policy reset to defaults.

---

13. Cheat Sheet

# Setup
phantom init                    # Create vault
phantom init --biometric        # Create vault + enable Touch ID
phantom mcp install             # Connect to Claude

# Secrets
phantom add SECRET_NAME         # Add secret (interactive)
phantom add KEY --from-env VAR  # Add from environment
phantom list                    # List all secrets
phantom show NAME --masked      # Show last 4 chars
phantom get NAME                # Get full value (TTY only)
phantom remove NAME             # Delete secret
phantom rotate NAME             # Rotate secret
phantom import .env             # Import from .env file

# Running commands
phantom run -s KEY -- cmd       # Inject secret into command

# Biometric (macOS)
phantom biometric status        # Check Touch ID status
phantom biometric enable        # Enable Touch ID
phantom biometric disable       # Disable Touch ID

# Namespaces
phantom namespace list          # List namespaces
phantom namespace create NAME   # Create namespace
phantom namespace use NAME      # Switch namespace
phantom namespace delete NAME   # Delete namespace

# Canary secrets
phantom canary create NAME      # Create honeypot secret
phantom canary list             # List canaries
phantom canary delete NAME      # Delete canary

# Security policies
phantom policy show             # View current policy
phantom policy set FILE         # Apply policy from file
phantom policy reset            # Reset to defaults

# Bulk edit (human-only, opens $EDITOR)
phantom edit                    # Edit whole vault as KEY=VALUE, re-encrypt on save

# Spending caps
phantom guardrail set NAME --cap 50 --provider openai  # Cap monthly spend
phantom guardrail status        # Usage vs cap for every guardrail

# Maintenance
phantom health                  # Check vault health
phantom audit --last N          # View last N audit entries
phantom passwd                  # Change master password (re-encrypts vault)
phantom update                  # Update phantom to latest version