CLI Reference

The secr CLI manages secrets from the terminal. All commands require authentication via secr login.

Installation

Homebrew (macOS / Linux)

brew tap secr-dev/secr
brew install secr

npm

npm install -g @secr/cli
secr --help

Commands

secr login

Authenticate with secr. Opens the dashboard in your browser and receives a token on callback. Credentials are saved to ~/.secr/credentials.json (mode 0600).

Browser-based login

secr login

Token-based login (CI)

secr login --token secr_tok_abc123...

secr logout

Clear saved credentials.

secr logout

secr whoami

Show current user and linked project.

secr whoami

secr init

Create a new project interactively.

secr init

secr link

Link the current directory to an existing project. Creates a .secr.json file (contains no secrets — commit this file).

secr link --org my-org --project my-api --env development

Option	Type	Required	Description
--org	string	Yes	Organization slug
--project	string	Yes	Project slug
--env	string	Yes	Default environment name

secr set

Create or update secrets.

Single secret

secr set DATABASE_URL=postgres://user:pass@host/mydb

With environment

secr set --env production API_KEY=sk_live_...

From .env file

secr set --from-env .env

secr pull

Pull secrets for the linked environment.

secr pull              # table format (default)
secr pull --format json
secr pull --format dotenv
secr pull --format table
secr pull --env staging

Option	Type	Required	Description
--format	string	table	Output format: table, json, or dotenv
--env	string	No	Override environment from .secr.json

secr run

Run a command with secrets injected into the environment.

secr run "npm start"
secr run "node server.js"
secr run --env staging "npm start"

secr ls

List secret keys (no values shown).

secr ls

secr delete

Delete one or more secrets (admin/owner only). Supports bulk deletion.

secr delete API_KEY
secr delete KEY_A KEY_B KEY_C

secr diff

Compare secrets between two environments.

secr diff --env staging production
secr diff --env staging production --reveal

Option	Type	Required	Description
--env	string	Yes	Two environment names to compare
--reveal	boolean	No	Show actual secret values in diff output

secr env

Manage project environments.

secr env list
secr env create qa

secr promote

Copy secrets from one environment to another.

secr promote --from development --to staging
secr promote --from development --to staging --dry-run
secr promote --from development --to staging --overwrite
secr promote --from development --to staging --keys DATABASE_URL,API_KEY

Option	Type	Required	Description
--from	string	Yes	Source environment
--to	string	Yes	Target environment
--dry-run	boolean	No	Preview changes without applying
--overwrite	boolean	No	Overwrite existing secrets in the target
--keys	string	No	Comma-separated list of specific keys to promote

secr template

Manage required key templates for a project.

secr template list
secr template add
secr template remove
secr template validate

secr rotate-key

Rotate the project encryption key (owner/admin only).

secr rotate-key

secr log

View recent audit log entries.

secr log

secr scan

Scan files for leaked secrets.

secr scan                # scan current directory
secr scan --pre-commit   # scan staged files only
secr scan --json         # JSON output
secr scan --list-patterns

Option	Type	Required	Description
--pre-commit	boolean	No	Scan only git-staged files
--json	boolean	No	Output results as JSON
--list-patterns	boolean	No	List all detection patterns

secr guard

Manage the git pre-commit hook for secret scanning.

secr guard install    # install pre-commit hook
secr guard uninstall  # remove pre-commit hook
secr guard status     # check hook status

secr org

Manage organizations.

secr org create my-team
secr org create my-team --slug my-team-slug
secr org delete my-org
secr org delete my-org --force

secr completion

Generate shell completion scripts.

Bash

eval "$(secr completion bash)"

Zsh

eval "$(secr completion zsh)"

Fish

secr completion fish > ~/.config/fish/completions/secr.fish

Environment Overrides

Most commands accept --env to override the default environment from .secr.json.

# Uses the default environment from .secr.json
secr pull

# Override to a specific environment
secr pull --env staging
secr set --env production API_KEY=sk_live_...
secr run --env staging "npm start"

Start managing secrets

npm install -g @secr/cli

Create Free Account Back to Docs