CLI Commands Reference
The SecretSpec CLI provides commands for managing secrets across different providers and profiles.
Initialize a new secretspec.toml configuration file from an existing .env file.
secretspec init [OPTIONS]
Options:
-f, --from <PATH>- Path to .env file to import from (default:.env)
Example:
$ secretspec init --from .env.example
✓ Created secretspec.toml with 5 secrets
Initialize user configuration interactively.
Example:
$ secretspec config init
? Select your preferred provider backend:
> keyring: System keychain
? Select your default profile:
> development
✓ Configuration saved to ~/.config/secretspec/config.toml
Display current configuration.
Example:
$ secretspec config show
Provider: keyring
Profile: development
config provider add
Add a provider alias to your configuration.
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 provider aliases.
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 configuration.
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 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 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 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 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
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
Environment Variables
| Variable | Description |
|---|---|
SECRETSPEC_PROFILE | Default profile to use |
SECRETSPEC_PROVIDER | Default provider to use |
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