Quick Start

Installation

Choose your preferred installation method:

$ curl -sSL https://install.secretspec.dev | sh

The static installer also installs secretspec-update. Run it to install the latest SecretSpec release:

$ secretspec-update

If you installed SecretSpec through Nix or another package manager, update it through that package manager instead.

Add to your devenv.nix:

{ config, ... }:
{
  # Secrets are automatically populated from secretspec.toml
  env.DATABASE_URL = config.secretspec.secrets.DATABASE_URL;
  env.REDIS_URL = config.secretspec.secrets.REDIS_URL;
}

$ nix-env -iA secretspec -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable

Getting started

Start with one project and the system keyring. You will declare the secrets the application expects, store one value, and run the application with that value in its environment.

1. Initialize `secretspec.toml`

From your project directory, create a manifest:

$ secretspec init

✓ Created secretspec.toml with 0 secrets

Next steps:
  1. secretspec config global init    # Set up user defaults (0.17+)
  2. secretspec check                 # Verify all secrets are set
  3. secretspec run -- your-command   # Run with secrets

This example assumes the project does not have a .env file. If one exists, init discovers its secret names automatically and reports the number of declarations it created. Review those declarations instead of replacing them in the next step. See Migration for details.

2. Declare your secrets

Edit secretspec.toml so it describes what your application expects:

[project]
name = "my-app"
revision = "1.0"

[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
SENTRY_DSN = { description = "Error reporting endpoint", required = false }

DATABASE_URL must be available before the application can run. SENTRY_DSN is optional, so leaving it unset does not block resolution. The manifest contains declarations, not secret values, and is safe to commit.

3. Store and use a secret

Store the required value in your system keyring:

$ secretspec set DATABASE_URL --provider keyring

Enter value for DATABASE_URL (profile: default): ********
✓ Secret 'DATABASE_URL' saved to keyring (profile: default)

Start your application with the resolved values in its environment:

$ secretspec run --provider keyring -- npm start

4. Configure your personal defaults

The commands above use --provider keyring explicitly. SecretSpec 0.17+ can save your preferred backend and default profile as preferences for your user:

$ secretspec config global init  # 0.17+
? Select your preferred provider backend:
> keyring: Uses system keychain (Recommended)
  kdbx: KeePass KDBX databases (0.17+)
  onepassword: 1Password password manager
  keeper: Keeper Secrets Manager (0.18+) via official Rust SDK
  dotenv: Traditional .env files
  file: Plaintext files, one per secret (0.19+)
  env: Read-only environment variables
  null: Use defaults, generation, or run prompts without storage (0.19+)
  systemd-credential: Read-only systemd service credentials (0.17+)
  pass: Unix password manager with GPG encryption
  gopass: Gopass CLI password manager with GPG encryption (0.15+)
  protonpass: Proton Pass via official pass-cli
  passbolt: Passbolt self-hosted password manager (0.19+) via go-passbolt-cli
  lastpass: LastPass password manager
  dashlane: Dashlane password manager, read-only (0.18+)
  gcsm: Google Cloud Secret Manager
  awssm: AWS Secrets Manager
  awsps: AWS Systems Manager Parameter Store (0.18+)
  scaleway: Scaleway Secret Manager (0.17+)
  vault: HashiCorp Vault secret management
  openbao: OpenBao secret management (0.17+)
  bw: Bitwarden Password Manager (0.18+)
  bws: Bitwarden Secrets Manager
  akv: Azure Key Vault
  infisical: Infisical secret management (0.16+)
  age: age-encrypted file (0.17+)
  sops: SOPS encrypted files (0.17+)
? Select your default profile:
  development
> default
  none
✓ Configuration saved to /home/user/.config/secretspec/config.toml

These preferences are stored in ~/.config/secretspec/config.toml. They are not written to the project, committed to version control, or shared with other users. They become your personal defaults across projects and can still be overridden by project configuration or command-line options.

You can now omit the provider from everyday commands:

$ secretspec set DATABASE_URL
$ secretspec check
$ secretspec run -- npm start

Next Steps

Continue with the commands in Basic Usage
Bring existing values into SecretSpec with the Migration guide
Learn about Profiles to manage environment-specific configurations
Explore different Providers for secret storage
Choose an SDK to resolve secrets from your application