▸ Agent Skills
2 min read

Basic Usage

The SecretSpec commands you will use most often

Once your project has a secretspec.toml file and you have selected a default provider, most day-to-day work uses a small set of commands.

Check required secrets

Check that every required secret can be resolved. Missing values are shown without printing any secrets, and SecretSpec offers to set them interactively:

$ secretspec check

Use secretspec check --no-prompt in CI or other non-interactive environments. It exits with an error when a required secret is missing.

Store or replace a value

Set a secret without putting its value in your shell history:

$ secretspec set API_KEY
Enter value for API_KEY (profile: development): ********
✓ Secret 'API_KEY' saved to keyring (profile: development)

Running set again replaces the stored value. The secret must already be declared in secretspec.toml.

Read one value

Resolve and print a single secret:

$ secretspec get DATABASE_URL
postgresql://localhost/myapp

Caution

get prints the secret as plain text. Avoid using it in shared terminals, logs, or scripts. Use run or an SDK when an application needs the value.

Run your application

Start a command with the resolved secrets available as environment variables:

$ secretspec run -- npm start

The -- separates SecretSpec’s options from the command you want to run. SecretSpec stops before starting the command if a required secret is missing.

Add a declaration

New in version 0.18

Declare a new secret without editing secretspec.toml by hand, then store its value:

$ secretspec add API_KEY --description "API access token"
$ secretspec set API_KEY

add changes only the declaration. It never asks for or stores the secret value.

Delete stored values

New in version 0.18

Remove a stored value from its provider:

$ secretspec delete API_KEY

This leaves the declaration in secretspec.toml, so the project still records that it expects API_KEY. See the CLI reference for deleting multiple values or using --all.

Use another profile or provider

Your configured defaults apply automatically. Override them for one command with --profile or --provider:

$ secretspec check --profile production
$ secretspec run --provider dotenv://.env.test -- npm test

These options do not change your saved preferences.

Next steps

Last updated Oct 11, 2026