CLI Commands Reference

The SecretSpec CLI provides commands for managing secrets across different providers and profiles.

Global Options

These options are available on every command:

Option	Description
-f, --file <FILE>	Path to secretspec.toml (default: auto-detect). Env: SECRETSPEC_FILE
--reason <REASON>	Reason for accessing secrets, recorded by providers that support audit logging (e.g. Proton Pass agent sessions). Takes precedence over PROTON_PASS_AGENT_REASON. Env: SECRETSPEC_REASON

$ secretspec run --reason "Deploying web frontend" -- ./deploy.sh

Commands

init

Initialize a new secretspec.toml configuration file from an existing .env file.

secretspec init [OPTIONS]

Options:

• --from <PATH> - Path to .env file to import from (default: .env)

Example:

$ secretspec init --from .env.example
✓ Created secretspec.toml with 5 secrets

config init

Initialize user configuration interactively.

secretspec config init

Example:

$ secretspec config init
? Select your preferred provider backend:
> keyring: System keychain
? Select your default profile:
> development
✓ Configuration saved to ~/.config/secretspec/config.toml

config show

Display current configuration.

secretspec config show

Example:

$ secretspec config show
Provider: keyring
Profile:  development

config provider add

Add a provider alias to your user-level configuration (~/.config/secretspec/config.toml).

To share aliases with your team, declare them in a top-level [providers] table in secretspec.toml instead — they take precedence over user-level aliases on name conflict.

secretspec config provider add <ALIAS> <URI>

Arguments:

• <ALIAS> - Short name for the provider (e.g., prod_vault, shared)
• <URI> - Provider URI (e.g., onepassword://vault/Production, env://)

Example:

$ secretspec config provider add prod_vault "onepassword://vault/Production"
✓ Provider alias 'prod_vault' saved

$ secretspec config provider add shared "onepassword://vault/Shared"
✓ Provider alias 'shared' saved

config provider list

List all configured user-level provider aliases. Project-level aliases declared in secretspec.toml are not shown by this command.

secretspec config provider list

Example:

$ secretspec config provider list
prod_vault  → onepassword://vault/Production
shared      → onepassword://vault/Shared
env         → env://

config provider remove

Remove a provider alias from your user-level configuration. To remove a project-level alias, edit the [providers] table in secretspec.toml directly.

secretspec config provider remove <ALIAS>

Arguments:

• <ALIAS> - Name of the alias to remove

Example:

$ secretspec config provider remove prod_vault
✓ Provider alias 'prod_vault' removed

check

Check if all required secrets are available, with interactive prompting for missing secrets.

secretspec check [OPTIONS]

Options:

• -p, --provider <PROVIDER> - Provider backend to use
• -P, --profile <PROFILE> - Profile to use

Example:

$ secretspec check --profile production
✓ DATABASE_URL - Database connection string
✗ API_KEY - API key for external service (required)
Enter value for API_KEY (profile: production): ****
✓ Secret 'API_KEY' saved to keyring (profile: production)

get

Get a secret value.

secretspec get [OPTIONS] <NAME>

Options:

• -p, --provider <PROVIDER> - Provider backend to use
• -P, --profile <PROFILE> - Profile to use

Example:

$ secretspec get DATABASE_URL --profile production
postgresql://prod.example.com/mydb

set

Set a secret value.

secretspec set [OPTIONS] <NAME> [VALUE]

Options:

• -p, --provider <PROVIDER> - Provider backend to use
• -P, --profile <PROFILE> - Profile to use

Example:

$ secretspec set API_KEY sk-1234567890
✓ Secret 'API_KEY' saved to keyring (profile: development)

run

Run a command with secrets injected as environment variables.

secretspec run [OPTIONS] -- <COMMAND>

Options:

• -p, --provider <PROVIDER> - Provider backend to use
• -P, --profile <PROFILE> - Profile to use

Examples:

# Run npm with secrets available as environment variables
$ secretspec run --profile production -- npm run deploy

# Verify secrets are injected
$ secretspec run -- env | grep DATABASE_URL
DATABASE_URL=postgresql://localhost/mydb

Shell Variable Expansion

Variables like $DATABASE_URL in the command line are expanded by your shell before secretspec runs. To use injected secrets in the command itself, wrap it in a subshell:

# This won't work - $DATABASE_URL is expanded before secretspec runs
$ secretspec run -- echo $DATABASE_URL
# Output: (empty, because DATABASE_URL isn't set in current shell)

# This works - variable expansion happens in the subprocess
$ secretspec run -- sh -c 'echo $DATABASE_URL'
# Output: postgresql://localhost/mydb

For most use cases, simply run your application and it will read secrets from its environment:

$ secretspec run -- node app.js  # app.js reads process.env.DATABASE_URL

import

Import secrets from one provider to another.

secretspec import <FROM_PROVIDER>

The destination provider and profile are determined from your configuration. Secrets that already exist in the destination provider will not be overwritten.

Arguments:

• <FROM_PROVIDER> - Provider to import from (e.g., env, dotenv:/path/to/.env)

Example:

# Import from environment variables to your default provider
$ secretspec import env
Importing secrets from env to keyring (profile: development)...

✓ DATABASE_URL - Database connection string
○ API_KEY - API key for external service (already exists in target)
✗ REDIS_URL - Redis connection URL (not found in source)

Summary: 1 imported, 1 already exists, 1 not found in source

# Import from a specific .env file
$ secretspec import dotenv:/home/user/old-project/.env

Use Cases:

• Migrate from .env files to a secure provider like keyring or OnePassword
• Copy secrets between different profiles or projects
• Import existing environment variables into SecretSpec management

audit

Show the local audit log of secret access.

secretspec audit [--project <NAME>] [--action <ACTION>] [-n <N>] [--json]

Options:

• --project <NAME> - Only show entries for this project
• --action <ACTION> - Only show entries for this action (get, set, check, run, import)
• -n, --tail <N> - Show only the last N entries
• --json - Output raw JSON Lines instead of the formatted summary

The log location is read from your user-global config ([audit] in ~/.config/secretspec/config.toml), defaulting to the per-user state directory.

Example:

$ secretspec audit --action run -n 5
2026-06-04T18:06:29Z  run    found  ./deploy.sh  API_KEY,DATABASE_URL  (my-app/production)  reason: deploy  [claude-code]

# Pipe raw entries to jq
$ secretspec audit --json | jq 'select(.outcome == "missing")'

Environment Variables

Variable	Description
SECRETSPEC_PROFILE	Default profile to use
SECRETSPEC_PROVIDER	Default provider to use
SECRETSPEC_FILE	Path to secretspec.toml (same as --file)
SECRETSPEC_REASON	Reason for accessing secrets (same as --reason)

Quick Start Workflow

# Initialize from existing .env
$ secretspec init --from .env

# Set up user configuration
$ secretspec config init

# Import existing secrets (optional)
$ secretspec import env  # or: secretspec import dotenv:.env.old

# Check and set missing secrets
$ secretspec check

# Run your application
$ secretspec run -- npm start