CLI Reference

PocketProtector’s CLI is its primary interface. The main command is pprotect (or equivalently, pocket_protector).

Global flags

These flags are available on all subcommands:

--file PATH: Path to the PocketProtector-managed file. Defaults to protected.yaml in the working directory.

--confirm: Show a diff and prompt for confirmation before modifying the file.

--non-interactive: Disable interactive prompts. The command fails if credentials cannot be resolved from flags or environment variables.

--user EMAIL, -u EMAIL: The acting user’s email credential.

--passphrase-file PATH: Path to a file containing only the passphrase, typically provided by a deployment system (Docker secrets, Kubernetes mounts).

--key-type TYPE: Custodian key type: hard (default, slow KDF), fast (quick KDF), or raw (no KDF, generated hex key).

--env-prefix PREFIX: Environment variable prefix for credential lookup. Default: PPROTECT. When set, credentials are read from PREFIX_USER and PREFIX_PASSPHRASE.

--output-format FORMAT: Output format for decrypt-domain: json (default), env (dotenv), or shell (export statements).

--secret NAME: Decrypt a single secret by name (decrypt-domain only).

--domain DOMAIN: Domain name (used by exec and other subcommands).

--prefix PREFIX: Prefix to prepend to secret env var names (exec only).

--uppercase: Convert secret names to UPPER_CASE env var names (exec only).

--no-passthrough: Start the child with a minimal environment (exec only).

Commands

init

pprotect init [--key-type TYPE]

Create a new protected.yaml file in the current directory and add the first key custodian. Prompts for the custodian’s email and passphrase.

This is equivalent to add-key-custodian but also creates the file.

add-key-custodian

pprotect add-key-custodian [--key-type TYPE]

Add a new key custodian to an existing protected file. Prompts for the custodian’s email and passphrase.

With --key-type raw, a 256-bit hex key is generated and displayed. You must type YES to confirm you have saved it.

add-domain

pprotect add-domain [-u EMAIL]

Add a new domain to the protected. Requires authentication as an existing key custodian, who becomes the initial owner of the domain. Prompts for the domain name.

rm-domain

pprotect rm-domain [-u EMAIL]

Remove a domain and all of its secrets from the protected. Prompts for the domain name. This operation is irreversible (use VCS to undo).

add-owner

pprotect add-owner [-u EMAIL]

Add a key custodian as an owner of a domain. The new owner must already be a key custodian. The authenticated user must already own the domain.

Prompts for the domain name and new owner email.

rm-owner

pprotect rm-owner [-u EMAIL]

Remove an owner from a domain. The domain must retain at least one owner. Prompts for the domain name and owner email to remove.

Note

After removing an owner, you should rotate-domain-keys to ensure the removed owner’s old keys can no longer decrypt secrets.

add-secret

pprotect add-secret

Add a new secret to a domain. Does not require authentication – secrets are encrypted using the domain’s public key. Prompts for domain name, secret name, and secret value.

Fails if the secret name already exists in the domain. Use update-secret to change an existing secret’s value.

update-secret

pprotect update-secret

Update the value of an existing secret in a domain. Does not require authentication. Prompts for domain name, secret name, and new value.

Fails if the secret does not exist. Use add-secret for new secrets.

rm-secret

pprotect rm-secret

Remove a secret from a domain. Does not require authentication. Prompts for domain name and secret name.

decrypt-domain

pprotect decrypt-domain [DOMAIN] [-u EMAIL] [--output-format FORMAT] [--secret NAME]

Decrypt and display the secrets for a domain. Requires authentication as a domain owner.

The domain name can be provided as a positional argument or via prompt.

Output format options:

json (default) – JSON object of all secrets
env – dotenv format (KEY="value")
shell – shell export format (export KEY="value")

With --secret NAME, only the named secret is printed. Without --output-format, the raw value is printed (no quoting).

exec

pprotect exec --domain DOMAIN [--prefix PREFIX] [--uppercase] [--no-passthrough] -- COMMAND [ARGS...]

Decrypt a domain and inject secrets as environment variables into a child process. This is the recommended way to pass secrets to applications.

The -- separator is required before the command to execute.

Flags:

--domain DOMAIN – required, the domain to decrypt
--prefix PREFIX – prepend PREFIX_ to each secret env var name
--uppercase – convert secret names to UPPER_CASE, replacing non-alphanumeric characters with underscores
--no-passthrough – start the child with a minimal environment (PATH, HOME, TERM, LANG, USER, SHELL, LOGNAME) plus decrypted secrets

Security properties:

Credential env vars (PPROTECT_USER, PPROTECT_PASSPHRASE, and any custom --env-prefix vars) are scrubbed from the child
On Unix, exec replaces the current process via os.execvpe – the passphrase never lingers in a parent shell
On Windows, subprocess.run is used instead

Example:

pprotect exec --domain prod --uppercase -- python run_service.py

set-key-custodian-passphrase

pprotect set-key-custodian-passphrase [--key-type TYPE]

Change a key custodian’s passphrase. Prompts for the custodian’s email, current passphrase, and new passphrase.

The custodian’s domain ownerships are preserved. Only the passphrase encryption changes.

rekey-custodian

pprotect rekey-custodian [-u EMAIL] [--key-type TYPE]

Re-encrypt a custodian’s key material with a new passphrase and optionally a different key type. This is useful when migrating from a human passphrase to an automated raw key for CI/CD.

All domain ownerships are preserved and re-encrypted with the new key material.

rotate-domain-keys

pprotect rotate-domain-keys [-u EMAIL]

Rotate the internal encryption keys for a domain. Generates a new keypair, re-encrypts all secrets and owner key shares. Only current owners retain access after rotation.

Requires authentication as a domain owner. Prompts for the domain name.

This should be done after any personnel change involving someone who had domain access.

migrate-owner

pprotect migrate-owner [-u EMAIL]

Grant a custodian ownership of all domains currently owned by the authenticated user. Prompts for the new owner email and confirmation.

Does not remove the original owner – that is a separate step.

list-domains

pprotect list-domains

Display all domain names in the protected, one per line.

list-domain-secrets

pprotect list-domain-secrets [DOMAIN]

Display all secret names within a domain, one per line. The domain name can be provided as a positional argument or via prompt.

list-all-secrets

pprotect list-all-secrets

Display all secrets across all domains. Each line shows a secret name followed by a colon and the domains that contain it:

chat-api-key: dev
mail-api-key: dev, prod

list-audit-log

pprotect list-audit-log

Display the audit log, one entry per line. Each entry includes a timestamp and a description of the operation performed.

list-user-secrets

pprotect list-user-secrets [-u EMAIL]

Display the domains and secrets accessible to the authenticated user. Requires authentication.

version

pprotect version

Display the current PocketProtector version and exit.