keypo-us/keypo-cli/keypo-signer

keypo-signer

A CLI for hardware-bound P-256 key management and encrypted secret storage using the Apple Secure Enclave. Keys never leave the hardware. Secrets are encrypted at rest and decrypted only into child process environments.

Install: brew install keypo-us/tap/keypo-signer This installs the keypo-signer Swift CLI for Secure Enclave key management and encrypted vault operations.

Source: https://github.com/keypo-us/keypo-cli

CLI Usage Rule

Before using any keypo-signer command for the first time in a session, run `keypo-signer help <command>` to learn the exact flags, syntax, and examples. The help output is the authoritative reference for each command.

keypo-signer help vault exec      # learn vault exec flags before using
keypo-signer help vault session   # learn session subcommands
keypo-signer help create          # learn create flags before creating keys

Do not guess flag names or assume positional arguments. Every command documents its interface via help.

Running Commands with Secrets (vault exec)

Use vault exec to inject decrypted secrets into a child process environment. The agent never sees plaintext values — secrets flow directly from the encrypted vault into the child process.

Basic patterns

# Using a .env.example file (recommended — values are ignored, only names matter)
keypo-signer vault exec --env .env.example -- cargo test
 
# Using explicit secret names
keypo-signer vault exec --allow PIMLICO_API_KEY,DEPLOYER_PRIVATE_KEY -- cargo test
 
# All secrets from all vaults
keypo-signer vault exec --allow '*' -- forge test -vvv

The .env.example convention

The --env flag reads a file for key names only — values are ignored. Use a .env.example with empty or dummy values:

# .env.example
PIMLICO_API_KEY=
DEPLOYER_PRIVATE_KEY=placeholder
BASE_SEPOLIA_RPC_URL=https://example.com

The vault looks up each name, finds which vault stores it, decrypts it, and injects it into the child process environment.

Combining --allow and --env

Both flags can be used together. Names are unioned and deduplicated:

keypo-signer vault exec --env .env.example --allow EXTRA_SECRET -- ./deploy.sh

Argument passing rules

The -- separator is required. Everything after -- is the command to execute.

Simple commands — pass the command and its arguments directly:

keypo-signer vault exec --env .env.example -- cargo test -- --ignored --test-threads=1
keypo-signer vault exec --allow '*' -- forge script Deploy

Shell expressions — when you need shell features (pipes, variable expansion, subshells), use sh -c:

keypo-signer vault exec --env .env.example -- sh -c 'echo $SECRET_NAME'
keypo-signer vault exec --allow '*' -- sh -c 'curl -H "Authorization: Bearer $API_KEY" https://api.example.com'

sh -c coalescing — when using sh -c, all arguments after -c are automatically joined into a single string. This means you don't need to quote the entire expression:

# These are equivalent:
keypo-signer vault exec --allow '*' -- sh -c 'echo $FOO && echo $BAR'
keypo-signer vault exec --allow '*' -- sh -c echo $FOO && echo $BAR

What NOT to do

• Never use vault get in agent workflows — it outputs plaintext to stdout. Use vault exec instead.
• Never retry after exit code 128 — the user deliberately cancelled authentication.
• Never attempt to read, log, capture, or exfiltrate secret values. Secrets must stay inside the child process.
• Never pipe vault get output into environment variables or files.

Exit codes

Behavioral details

Common patterns

# Run integration tests with secrets
keypo-signer vault exec --env .env.example -- cargo test -- --ignored --test-threads=1
 
# Run Foundry tests
keypo-signer vault exec --env .env.example -- forge test -vvv
 
# Deploy contracts
keypo-signer vault exec --allow DEPLOYER_PRIVATE_KEY -- forge script Deploy
 
# Multi-tool composition: secrets + keypo-wallet
keypo-signer vault exec --allow PIMLICO_API_KEY --allow KEYPO_RPC_URL -- keypo-wallet send --key agent --to 0x... --value 1000
 
# Check what secrets are available (no auth required)
keypo-signer vault list

Sessions (Unattended Agent Workflows)

Sessions let a human authenticate once and grant scoped, time-limited access to specific secrets. After session creation, vault exec --session runs without auth prompts — ideal for agent workflows that need repeated access to protected secrets.

Create a session

# Authenticate once, grant 30-minute access to specific secrets
keypo-signer vault session start --secrets API_KEY,DB_PASSWORD --ttl 30m
 
# With a usage limit
keypo-signer vault session start --secrets API_KEY --ttl 1h --max-uses 50

The human approves via Touch ID (if secrets are in biometric vault), and a session is created with a random name (e.g., orbital-canvas).

Use a session

# No auth prompt — session handles it
keypo-signer vault exec --session orbital-canvas -- npm start
keypo-signer vault exec --session orbital-canvas -- python app.py

--session is mutually exclusive with --allow and --env. The session fully defines which secrets are injected.

Manage sessions

# List active sessions
keypo-signer vault session list
 
# Check session details (secrets, TTL, uses remaining)
keypo-signer vault session status orbital-canvas
 
# Extend a session (re-authenticates)
keypo-signer vault session refresh orbital-canvas --ttl 2h
 
# End a session early
keypo-signer vault session end orbital-canvas
 
# End all sessions
keypo-signer vault session end --all

Agent workflow pattern

The recommended pattern for agents that need protected secrets:

1. Human creates a session (one-time, interactive):

``bash keypo-signer vault session start --secrets API_KEY,DB_PASS --ttl 1h --max-uses 100 ``

1. Agent uses the session (repeated, unattended):

``bash keypo-signer vault exec --session <name> -- <agent-command> ``

1. Session expires automatically after TTL or usage limit.

Session security

• Sessions are scoped to specific secrets — they cannot access other secrets.
• Secrets are re-encrypted under a temporary SE key. The session is self-contained.
• Every session action is recorded in an audit log at ~/.keypo/session-audit.log.
• Sessions expire after TTL or usage limit. Expired sessions are cleaned up automatically.

Storing Secrets

Initialize vaults

keypo-signer vault init

Creates three vaults: open, passcode, and biometric. Each is backed by its own Secure Enclave key.

Store a secret

echo -n "sk_live_abc123" | keypo-signer vault set API_KEY --vault biometric
keypo-signer vault set DB_PASSWORD --vault passcode

Pipe the value via stdin, or omit it to be prompted interactively. Default vault is the highest available tier.

Bulk import from .env file

keypo-signer vault import .env --vault passcode

Reads key=value pairs from the file and stores each as a separate secret.

Update a secret

keypo-signer vault update MY_API_KEY

Prompts for the new value. The secret stays in its original vault.

Delete a secret

keypo-signer vault delete MY_API_KEY --confirm

The --confirm flag is required to prevent accidental deletion.

List secrets (safe, no auth)

keypo-signer vault list

Shows vault names and secret names. No decryption occurs.

Destroy all vaults

keypo-signer vault destroy --confirm

Permanently deletes all vaults, secrets, and vault keys. Irreversible.

Backup & Restore

Back up to iCloud Drive

keypo-signer vault backup

Encrypts all vault secrets and writes them to iCloud Drive. Encryption uses two factors: an iCloud Keychain synced key + a passphrase displayed once. Both are required to restore.

Check backup status

keypo-signer vault backup-info

Shows whether a backup exists, its age, and any unbackup'd secrets.

Restore from backup

keypo-signer vault restore
keypo-signer vault restore --previous

Decrypts the backup, compares to local vault, and offers: cancel, replace, merge, or back-up-first. --previous restores from the prior backup instead of the current one.

Reset backup key

keypo-signer vault backup-reset

Regenerates the backup encryption key and passphrase. Use when you suspect the passphrase was compromised.

Vault Policies

For agent workflows, store secrets in open or passcode vaults. biometric requires interactive Touch ID which blocks automation — use sessions to grant time-limited access to biometric secrets without repeated prompts.

Key Management

Create a key

keypo-signer create --label my-key --policy open

Generates a P-256 key in the Secure Enclave. Policies: open, passcode, biometric.

List keys

keypo-signer list

Shows all managed keys with labels, policies, and creation dates.

Key details

keypo-signer info my-key

Shows public key, policy, and metadata for a specific key.

Sign a digest

keypo-signer sign 0xdeadbeef --key my-key

Signs raw hex-encoded data. Uses prehash signing (no double-hashing). Output is a DER-encoded P-256 signature.

Verify a signature

keypo-signer verify 0xdeadbeef 0x3045... --key my-key
keypo-signer verify 0xdeadbeef 0x3045... --public-key 0x04abcd...

Delete a key

keypo-signer delete my-key --confirm

Permanently destroys the key from the Secure Enclave. Irreversible.

Rotate a key

keypo-signer rotate my-key

Generates a new key with the same label and policy, replacing the old one.

Commands Reference