Quick Start

Installation

Choose your preferred installation method:

curl -sSL https://install.secretspec.dev | 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-env -iA secretspec -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable

Getting Started

Follow these steps to get started with SecretSpec:

1. Initialize `secretspec.toml`

Discover secrets from existing .env files:

$ secretspec init
✓ Created secretspec.toml with 0 secrets

Next steps:
  1. secretspec config init    # Set up user configuration
  2. secretspec check          # Verify all secrets are set
  3. secretspec run -- your-command  # Run with secrets

If you have an existing .env file, you can import secrets from it:

$ secretspec init --from .env

Now edit secretspec.toml to define the secrets your application needs:

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

[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
REDIS_URL = { description = "Redis connection string", required = false }

[profiles.development]
DATABASE_URL = { default = "sqlite://./dev.db" }

[profiles.production]
REDIS_URL = { required = true }

2. Set up provider backend

Configure your preferred secrets storage backend:

$ secretspec config init
? Select your preferred provider backend:
> onepassword: OnePassword password manager
  dotenv: Traditional .env files
  env: Read-only environment variables
  keyring: Uses system keychain (Recommended)
  lastpass: LastPass password manager
? Select your default profile:
> development
  default
  none
✓ Configuration saved to /home/user/.config/secretspec/config.toml

3. Import existing secrets (optional)

If you have existing secrets in environment variables or another .env file, you can import them:

# Import from current environment variables
$ secretspec import env

# Import from another .env file
$ secretspec import dotenv:/path/to/old/.env

4. Check and configure secrets

Verify that all required secrets are configured:

$ secretspec check

If any secrets are missing, you’ll be prompted to set them. You can also set secrets manually:

$ secretspec set DATABASE_URL
Enter value for DATABASE_URL: postgresql://localhost/myapp
✓ Secret DATABASE_URL saved

5. Run your application

Run your application with secrets injected as environment variables:

$ secretspec run -- npm start

# Or with a specific profile and provider
$ secretspec run --profile production --provider dotenv -- npm start

Next Steps

Learn about Profiles to manage environment-specific configurations
Explore different Providers for secret storage
Set up the Rust SDK for type-safe secret access in your code