Quick Start

Get up and running with SecretSpec in minutes

Installation

Choose your preferred installation method:

• Static Binary

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

  SecretSpec 0.20+ provides static musl CLI binaries for x64 and arm64 Linux, so the installer works directly on Alpine without a glibc compatibility layer.

  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.

• Brew

  brew install secretspec

• WinGet

  winget install --exact --id Cachix.SecretSpec

• Devenv.sh

  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

  $ 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:

secretspec.toml

[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
  doppler: Doppler secret management (0.21+)
  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+)
  fly: Fly.io application secrets via flyctl, write-only (0.20+)
  cloudflare: Cloudflare Secrets Store, write-only (0.20+)
  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+)
  setec: Tailscale Setec secrets service (0.21+)
  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
  aac: Azure App Configuration (0.20+)
  infisical: Infisical secret management (0.16+)
  ejson: EJSON encrypted files, read-only (0.20+)
  age: age-encrypted file (0.17+)
  sops: SOPS encrypted files (0.17+)
  kubernetes: Kubernetes (0.20+)
? 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

Last updated Oct 11, 2026