SecretSpec

https://secretspec.dev
Admin
SecretSpec separates secret declaration from provisioning, allowing applications to declare their...
Tokens:34,042
Snippets:462
Trust Score:5.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install via Nix

Source: https://secretspec.dev/quick-start

Install the package using nix-env.

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

--------------------------------

### Example Provider Implementation

Source: https://secretspec.dev/reference/adding-providers

A complete example showing configuration definition, URL parsing, and Provider trait implementation.

```rust
use super::Provider;
use crate::{Result, SecretSpecError};
use url::Url;
use serde::{Deserialize, Serialize};


#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MyBackendConfig {
    pub endpoint: Option<String>,
}


impl Default for MyBackendConfig {
    fn default() -> Self {
        Self { endpoint: None }
    }
}


impl TryFrom<&Url> for MyBackendConfig {
    type Error = SecretSpecError;


    fn try_from(url: &Url) -> std::result::Result<Self, Self::Error> {
        if url.scheme() != "mybackend" {
            return Err(SecretSpecError::ProviderOperationFailed(
                format!("Invalid scheme '{}' for mybackend provider", url.scheme())
            ));
        }


        // Parse URL into configuration
        Ok(Self {
            endpoint: url.host_str().map(|s| s.to_string()),
        })
    }
}


pub struct MyBackendProvider {
    config: MyBackendConfig,
}


crate::register_provider! {
    struct: MyBackendProvider,
    config: MyBackendConfig,
    name: "mybackend",
    description: "My custom backend provider",
    schemes: ["mybackend"],
    examples: ["mybackend://api.example.com", "mybackend://localhost:8080"],
}


impl MyBackendProvider {
    pub fn new(config: MyBackendConfig) -> Self {
        Self { config }
    }
}


impl Provider for MyBackendProvider {
    fn name(&self) -> &'static str {
        Self::PROVIDER_NAME
    }


    fn uri(&self) -> String {
        "mybackend".to_string()
    }


    fn convention_address(&self, project: &str, profile: &str, key: &str)
        -> Result<NativeAddress> {
        Ok(NativeAddress {
            item: format!("secretspec/{}/{}/{}", project, profile, key),
            ..Default::default()
        })
    }


    fn get(&self, addr: Address<'_>) -> Result<Option<SecretString>> {
        let coords = self.resolve_coords(addr)?;
        // Reject coordinates the store cannot honor, then read coords.item
        Ok(None)
    }


    fn set(&self, addr: Address<'_>, value: &SecretString) -> Result<()> {
        let coords = self.resolve_coords(addr)?;
        // Write value at coords.item
        Ok(())
    }
}
```

--------------------------------

### Install SecretSpec SDKs

Source: https://secretspec.dev/blog/secretspec-0-13-sdks

Installation commands for various language-specific SDKs.

```bash
pip install secretspec                              # Python
npm install secretspec                              # Node.js / TypeScript
gem install secretspec                              # Ruby
go get github.com/cachix/secretspec/secretspec-go   # Go
```

--------------------------------

### Configure Pass provider examples

Source: https://secretspec.dev/providers/pass

Examples of setting secrets using default storage, custom folder prefixes, and custom store directories.

```bash
# Use default pass storage
$ secretspec set DATABASE_URL --provider pass


# Custom folder prefix (e.g., to share secrets across projects — see below)
$ secretspec set DATABASE_URL --provider "pass://shared/{profile}/{key}"


# Custom password store directory
$ secretspec set DATABASE_URL --provider "pass://?store_dir=/path/to/store"
```

--------------------------------

### Proton Pass URI Examples

Source: https://secretspec.dev/providers/protonpass

Examples of URI configurations for default and specific vaults with custom templates.

```text
# Default vault ("secretspec")
protonpass://


# Specific vault
protonpass://Work


# Specific vault and custom title template
protonpass://Work/{project}/{profile}/{key}
```

--------------------------------

### Install gnome-keyring on Linux

Source: https://secretspec.dev/providers/keyring

Install the required gnome-keyring package on Linux distributions if it is missing.

```bash
# Debian/Ubuntu
$ sudo apt-get install gnome-keyring


# Fedora
$ sudo dnf install gnome-keyring


# Arch
$ sudo pacman -S gnome-keyring
```

--------------------------------

### Install SecretSpec via Static Binary

Source: https://secretspec.dev/quick-start

Use the shell script to install the static binary.

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

--------------------------------

### Vault Provider Usage Commands

Source: https://secretspec.dev/providers/vault

Examples of using default mounts, custom mounts, and OpenBao.

```bash
# With default "secret" mount
$ secretspec set DATABASE_URL --provider vault://vault.example.com:8200
Enter value for DATABASE_URL: postgresql://localhost/mydb
✓ Secret 'DATABASE_URL' saved to vault (profile: default)


# With custom mount
$ secretspec set API_KEY --provider vault://vault.example.com:8200/custom-kv


# Using OpenBao
$ secretspec check --provider openbao://bao.internal:8200/secret
```

--------------------------------

### Keyring Provider URI Example

Source: https://secretspec.dev/reference/providers

Defines the URI format for accessing the system keychain.

```text
keyring://                   # System default keychain
```

--------------------------------

### Bitwarden Secrets Manager URI Examples

Source: https://secretspec.dev/reference/providers

Examples of URI formats for connecting to different Bitwarden Secrets Manager instances.

```text
bws://a9230ec4-5507-4870-b8b5-b3f500587e4c                    # US cloud (default)
bws://vault.bitwarden.eu@a9230ec4-5507-4870-b8b5-b3f500587e4c # EU cloud
bws://bw.example.com@a9230ec4-5507-4870-b8b5-b3f500587e4c     # Self hosted
```

--------------------------------

### Environment Provider URI Example

Source: https://secretspec.dev/reference/providers

Defines the URI format for accessing system environment variables.

```text
env://                       # Current process environment
```

--------------------------------

### Monorepo structure example

Source: https://secretspec.dev/concepts/inheritance

Visual representation of a directory structure utilizing configuration inheritance.

```text

monorepo/
├── shared/
│   ├── base/secretspec.toml      # Common secrets
│   └── database/secretspec.toml  # DB-specific (extends base)
└── services/
    ├── api/secretspec.toml       # API service (extends database)
    └── frontend/secretspec.toml  # Frontend (extends base)

```

--------------------------------

### Quick start with SecretSpec

Source: https://secretspec.dev/sdk/python

Initialize the SecretSpec builder, load secrets from a provider, and export them to environment variables.

```python
from secretspec import SecretSpec


resolved = (
    SecretSpec.builder()
    .with_provider("keyring://")
    .with_profile("production")
    .with_reason("boot web app")
    .load()
)


print(resolved.provider, resolved.profile)
db = resolved.secrets["DATABASE_URL"]
print(db.get)              # the value, or the file path for as_path secrets
resolved.set_as_env()      # export everything into os.environ
```

--------------------------------

### Supplying Audit Reasons via CLI, SDK, and Environment

Source: https://secretspec.dev/blog/secretspec-0-12-audit-logs-and-coding-agents

Examples of the three methods to provide an audit reason, ordered by precedence.

```bash
# CLI: the most explicit option, overrides the others
secretspec run --reason "deploying release 0.12" -- ./deploy.sh
```

```rust
// SDK: the programmatic equivalent of --reason
let secrets = Secrets::load(/* ... */)?.with_reason("nightly backup job");
```

```bash
# Env: lowest precedence, but honored everywhere
export SECRETSPEC_REASON="nightly backup job"
```

--------------------------------

### Web Application Profile Configuration

Source: https://secretspec.dev/concepts/profiles

A practical example showing environment-specific overrides for a web application project.

```toml
[project]
name = "web-app"
revision = "1.0"


[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection", required = true }
REDIS_URL = { description = "Redis for caching", required = true }
JWT_SECRET = { description = "JWT signing key", required = true }


[profiles.development]
# Inherits all secrets from default, just adding defaults
DATABASE_URL = { default = "postgresql://localhost:5432/webapp_dev" }
REDIS_URL = { default = "redis://localhost:6379/0" }
JWT_SECRET = { default = "dev-secret-change-in-prod" }
HOT_RELOAD = { description = "Enable hot reload", required = false, default = "true" }


[profiles.production]
# Inherits DATABASE_URL, REDIS_URL, JWT_SECRET from default
# Only adds production-specific secrets
SENTRY_DSN = { description = "Error tracking", required = true }
SSL_CERT = { description = "SSL certificate path", required = true }
```

--------------------------------

### Install SecretSpec CLI and Rust SDK

Source: https://secretspec.dev/blog/secretspec-0-13-sdks

Standard installation command for the SecretSpec CLI and Rust SDK via Cargo.

```bash
cargo install secretspec
```

--------------------------------

### Command Line Provider Selection

Source: https://secretspec.dev/reference/providers

Usage examples for specifying providers via the command line using simple names or configuration URIs.

```bash
# Simple provider names
secretspec get API_KEY --provider keyring
secretspec get API_KEY --provider dotenv
secretspec get API_KEY --provider env


# URIs with configuration
secretspec get API_KEY --provider dotenv:/path/to/.env
secretspec get API_KEY --provider onepassword://vault
secretspec get API_KEY --provider "onepassword://account@vault"
```

--------------------------------

### CI/CD Integration

Source: https://secretspec.dev/providers/awssm

Examples of running commands in CI/CD environments using environment variables or IAM roles.

```bash
# Using environment variables
$ export AWS_ACCESS_KEY_ID=AKIA...
$ export AWS_SECRET_ACCESS_KEY=...
$ export AWS_DEFAULT_REGION=us-east-1


# Run command
$ secretspec run --provider awssm://us-east-1 -- deploy


# Or with IAM roles (no credentials needed)
$ secretspec run --provider awssm://us-east-1 -- deploy
```

--------------------------------

### Install LastPass CLI

Source: https://secretspec.dev/providers/lastpass

Commands to install the LastPass CLI tool on various operating systems.

```bash
# macOS
brew install lastpass-cli


# Linux (apt)
sudo apt install lastpass-cli


# NixOS
nix-env -iA nixpkgs.lastpass-cli
```

--------------------------------

### Install pass on various operating systems

Source: https://secretspec.dev/providers/pass

Commands to install the pass utility on Debian/Ubuntu, Fedora, Arch, and macOS.

```bash
# Debian/Ubuntu
$ sudo apt-get install pass


# Fedora
$ sudo dnf install pass


# Arch
$ sudo pacman -S pass


# macOS
$ brew install pass
```

--------------------------------

### Configure Provider-Specific Vaults

Source: https://secretspec.dev/reference/configuration

Examples showing how to handle vault mounts and overrides for Vault and 1Password providers.

```toml
# The mount `kv2` comes from the URI; the ref names the path inside it.
DB = { description = "DB", ref = { item = "myapp/config", field = "pw" }, providers = ["vault://vault.example.com:8200/kv2"] }


# 1Password: `vault` on the ref overrides the URI's default vault.
TOKEN = { description = "Token", ref = { vault = "Production", item = "infra", field = "token" }, providers = ["onepassword://Private"] }
```

--------------------------------

### Import secrets from dotenv

Source: https://secretspec.dev/

Example of a .env file format used as a source for secret migration.

```text
DATABASE_URL=postgres://…
STRIPE_SECRET_KEY=sk_live_…
REDIS_URL=redis://…
```

--------------------------------

### Implement Complete SecretSpec Configuration

Source: https://secretspec.dev/concepts/declarative

Example of a full configuration file utilizing inheritance and service-specific secret definitions.

```toml
[project]
name = "web-api"
revision = "2.1.0"
extends = ["../shared/base", "../shared/auth"]


[profiles.default]
# Inherits DATABASE_URL, LOG_LEVEL from base
# Inherits JWT_SECRET, SESSION_SECRET from auth
# Service-specific additions:
STRIPE_API_KEY = { description = "Stripe payment API", required = true }
REDIS_URL = { description = "Redis cache connection", required = true }
PORT = { description = "Server port", required = false, default = "3000" }
```

--------------------------------

### Complete Project Configuration

Source: https://secretspec.dev/reference/configuration

A full example of a secretspec.toml file defining project metadata, provider aliases, and multiple profiles.

```toml
[project]
name = "web-api"
revision = "1.0"
extends = ["../shared/secretspec.toml"]  # Optional inheritance


# Provider aliases used by profile provider chains
[providers]
prod_vault = "onepassword://Production"
shared_vault = "onepassword://Shared"
keyring = "keyring://"
env = "env://"


# Default profile - always loaded first
[profiles.default]
APP_NAME = { description = "Application name", required = false, default = "MyApp" }
LOG_LEVEL = { description = "Log verbosity", required = false, default = "info" }
GITHUB_TOKEN = { description = "GitHub token", required = true, providers = ["env"] }


# Development profile - extends default
[profiles.development]
DATABASE_URL = { description = "Database connection", required = false, default = "sqlite://./dev.db" }
API_URL = { description = "API endpoint", required = false, default = "http://localhost:3000" }
DEBUG = { description = "Debug mode", required = false, default = "true" }


# Production profile - extends default
[profiles.production]
DATABASE_URL = { description = "PostgreSQL cluster connection", required = true, providers = ["prod_vault", "keyring"] }
API_URL = { description = "Production API endpoint", required = true }
SENTRY_DSN = { description = "Error tracking service", required = true, providers = ["shared_vault"] }
REDIS_URL = { description = "Redis cache connection", required = true }
```

--------------------------------

### Execute CI/CD Commands

Source: https://secretspec.dev/providers/bws

Example of using BWS in a CI/CD pipeline by setting the access token from environment variables.

```bash
# Set access token (from CI secrets)
$ export BWS_ACCESS_TOKEN="$BWS_TOKEN"


# Run command
$ secretspec run --provider bws://a9230ec4-5507-4870-b8b5-b3f500587e4c -- deploy
```

--------------------------------

### LastPass Provider URI Examples

Source: https://secretspec.dev/reference/providers

Defines the URI format for integrating with LastPass via the lpass CLI.

```text
lastpass://work              # Store in work folder
lastpass:///personal/projects # Nested folder
lastpass://localhost         # Root (no folder)
```

--------------------------------

### Retrying with a Reason

Source: https://secretspec.dev/blog

Example of retrying a command by providing a reason via the --reason flag.

```bash
secretspec run --reason "run the test suite before opening a PR" -- npm test
```

--------------------------------

### DotEnv Provider URI Examples

Source: https://secretspec.dev/reference/providers

Defines the URI format for accessing secrets stored in .env files.

```text
dotenv://                    # Uses default .env
dotenv:///config/.env        # Custom path
dotenv://config/.env         # Relative path
```

--------------------------------

### SecretSpec Quick Start Workflow

Source: https://secretspec.dev/reference/cli

A sequence of commands to initialize, configure, import, check, and run an application using the SecretSpec CLI.

```bash
# 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
```

--------------------------------

### Comprehensive Secret Generation Examples

Source: https://secretspec.dev/concepts/generation

Demonstrates various generation configurations including custom lengths, character sets, RSA key sizes, and informational-only types.

```toml
[profiles.default]
# Auto-generated on first run, reused after that
DB_PASSWORD = { description = "Database password", type = "password", generate = true }


# Custom length and character set
ADMIN_PASSWORD = { description = "Admin password", type = "password", generate = { length = 64, charset = "ascii" } }


# 64-byte key encoded as base64
ENCRYPTION_KEY = { description = "Encryption key", type = "base64", generate = { bytes = 64 } }


# RSA private key (default 2048-bit)
JWT_SIGNING_KEY = { description = "JWT signing key", type = "rsa_private_key", generate = true }


# RSA private key with custom key size
TLS_KEY = { description = "TLS private key", type = "rsa_private_key", generate = { bits = 4096 } }


# Informational type only, no generation
EXTERNAL_API_KEY = { description = "Provided by vendor", type = "password" }
```

--------------------------------

### Reference Secrets in Configuration

Source: https://secretspec.dev/providers/lastpass

Example of referencing a specific LastPass item within a profile configuration.

```toml
[profiles.production]
DATABASE_URL = { description = "DB", ref = { item = "Shared-Infra/Production DB" }, providers = ["lastpass"] }
```

--------------------------------

### CLI Examples for AWS Secrets Manager

Source: https://secretspec.dev/providers/awssm

Common CLI commands for setting, checking, and retrieving secrets using the awssm provider.

```bash
# Set a secret (SDK default credentials)
$ secretspec set DATABASE_URL --provider awssm://us-east-1


# Use a specific AWS profile
$ secretspec check --provider awssm://production@us-east-1


# Use a prefix to scope secrets under "myteam/"
$ secretspec set DATABASE_URL --provider "awssm://us-east-1?prefix=myteam"


# Get a secret
$ secretspec get DATABASE_URL --provider awssm://us-east-1


# Run with secrets
$ secretspec run --provider awssm://us-east-1 -- npm start


# Use SDK defaults for both profile and region
$ secretspec set DATABASE_URL --provider awssm
```

--------------------------------

### Verify stored secret path

Source: https://secretspec.dev/providers/pass

Example command to display a secret stored in the hierarchical structure.

```bash
$ pass show secretspec/myapp/default/DATABASE_URL
postgresql://localhost/mydb
```

--------------------------------

### Translate URI to Table Reference

Source: https://secretspec.dev/reference/configuration

Example of converting a 1Password URI string into the required table-based ref format.

```toml
INFRA_TOKEN = { description = "Infra token", ref = { vault = "Production", item = "infra", field = "token" }, providers = ["onepassword://Production"] }
```

--------------------------------

### Configure Secret Reference

Source: https://secretspec.dev/providers/protonpass

Example of mapping a secret to a specific item title in a Proton Pass vault.

```toml
[profiles.production]
DATABASE_URL = { description = "DB", ref = { item = "Production Database" }, providers = ["protonpass://Work"] }
```

--------------------------------

### Set Secrets via CLI

Source: https://secretspec.dev/providers/onepassword

Examples of using the secretspec CLI to set secrets using various 1Password provider configurations.

```bash
# Use specific vault
$ secretspec set API_KEY --provider onepassword://Production


# Use specific account and vault
$ secretspec set DATABASE_URL --provider "onepassword://work@DevVault"


# Use service account token
$ secretspec set SECRET --provider "onepassword+token://ops_token123@Production"


# Default vault (Private)
$ secretspec set KEY --provider onepassword://
```

--------------------------------

### Use shared secret in project configuration

Source: https://secretspec.dev/providers/pass

Example of using a shared provider for a secret across multiple projects.

```toml
# secretspec.toml (in project-A and project-B)
[profiles.default]
ARTIFACTORY_USER = { description = "Artifactory user", providers = ["shared"] }
```

--------------------------------

### Initialize user configuration

Source: https://secretspec.dev/reference/cli

Interactively set up user-level configuration.

```bash
secretspec config init
```

```bash
$ secretspec config init
? Select your preferred provider backend:
> keyring: System keychain
? Select your default profile:
> development
✓ Configuration saved to ~/.config/secretspec/config.toml
```

--------------------------------

### Initialize Provider Backend

Source: https://secretspec.dev/quick-start

Configure the storage backend for secrets.

```bash
$ secretspec config init
? Select your preferred provider backend:
> keyring: Uses system keychain (Recommended)
  onepassword: OnePassword password manager
  dotenv: Traditional .env files
  env: Read-only environment variables
  pass: Unix password manager with GPG encryption
  protonpass: Proton Pass via official pass-cli
  lastpass: LastPass password manager
  gcsm: Google Cloud Secret Manager
  awssm: AWS Secrets Manager
  vault: HashiCorp Vault / OpenBao secret management
  bws: Bitwarden Secrets Manager
? Select your default profile:
> development
  default
  none
✓ Configuration saved to /home/user/.config/secretspec/config.toml
```

--------------------------------

### secretspec get

Source: https://secretspec.dev/reference/cli

Retrieves the value of a specific secret.

```APIDOC
## secretspec get

### Description
Get a secret value.

### Arguments
- **NAME** (string) - Required - The name of the secret to retrieve

### Options
- **-p, --provider** (string) - Optional - Provider backend to use
- **-P, --profile** (string) - Optional - Profile to use
```

--------------------------------

### Configure CI/CD with Service Accounts

Source: https://secretspec.dev/providers/gcsm

Authenticate using a service account key file before running commands.

```bash
# Set credentials
$ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"


# Run command
$ secretspec run --provider gcsm://my-gcp-project -- deploy
```

--------------------------------

### Get secret value

Source: https://secretspec.dev/reference/cli

Retrieve the value of a specific secret for a given profile.

```bash
secretspec get [OPTIONS] <NAME>
```

```bash
$ secretspec get DATABASE_URL --profile production
postgresql://prod.example.com/mydb
```

--------------------------------

### Initialize SecretSpec

Source: https://secretspec.dev/quick-start

Initialize the project configuration and import from existing files.

```bash
$ 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
```

```bash
$ secretspec init --from .env
```

--------------------------------

### Initialize and load secrets

Source: https://secretspec.dev/sdk/go

Basic usage pattern for initializing the client, configuring providers, and accessing secret values.

```go
import secretspec "github.com/cachix/secretspec/secretspec-go"


resolved, err := secretspec.New().
    WithProvider("keyring://").
    WithProfile("production").
    WithReason("boot web app").
    Load()
if err != nil {
    log.Fatal(err)
}


fmt.Println(resolved.Provider, resolved.Profile)
db := resolved.Secrets["DATABASE_URL"]
fmt.Println(db.Get()) // the value, or the file path for as_path secrets
resolved.SetAsEnv()   // export everything into the process environment
```

--------------------------------

### Provider Error Message

Source: https://secretspec.dev/blog/secretspec-0-14-secret-references

Example of an error message returned when an unsupported coordinate is used for a provider.

```text
Error: Provider operation failed: the env provider does not support the `field` coordinate. Drop `field` from the ref for `GITHUB_PAT`.
```

--------------------------------

### Environment Provider Secret Reference

Source: https://secretspec.dev/blog/secretspec-0-14-secret-references

Example of a secret reference configuration for an environment variable provider.

```hcl
GITHUB_TOKEN = { description = "GitHub token", ref = { item = "GITHUB_PAT", field = "x" }, providers = ["env"] }
```

--------------------------------

### Display current configuration

Source: https://secretspec.dev/reference/cli

Show the currently active provider and profile settings.

```bash
secretspec config show
```

```bash
$ secretspec config show
Provider: keyring
Profile:  development
```

--------------------------------

### Execute with Environment Variables

Source: https://secretspec.dev/providers/env

Set environment variables in the shell and use the provider to verify or run applications.

```bash
# Set environment variables
export DATABASE_URL="postgresql://localhost/mydb"
export API_KEY="sk-1234567890"


# Check secrets are available
$ secretspec check --provider env
✓ All required secrets are configured


# Run with environment variables
$ secretspec run --provider env -- npm start
```

--------------------------------

### Initialize Default Provider

Source: https://secretspec.dev/concepts/providers

Sets the default provider for the project using the CLI.

```bash

$ secretspec config init

```

--------------------------------

### Basic Usage Commands

Source: https://secretspec.dev/providers/awssm

Standard commands for setting secrets and importing environment variables.

```bash
# Set a secret
$ secretspec set DATABASE_URL --provider awssm://us-east-1
Enter value for DATABASE_URL: postgresql://localhost/mydb
✓ Secret 'DATABASE_URL' saved to awssm (profile: default)


# Import from .env
$ secretspec import dotenv://.env
```

--------------------------------

### Define secret reference in TOML

Source: https://secretspec.dev/providers/pass

Example of referencing an existing pass entry within a configuration file.

```toml
[profiles.default]
GITHUB_TOKEN = { description = "GH token", ref = { item = "github/token" }, providers = ["pass"] }
```

--------------------------------

### Initialize and Load Secrets

Source: https://secretspec.dev/

Demonstrates how to initialize the SecretSpec builder, configure a provider and reason, and retrieve a secret value across different programming languages.

```python
from secretspec import SecretSpec

s = SecretSpec.builder() \
    .with_provider("keyring://") \
    .with_reason("boot").load()
print(s.secrets["DATABASE_URL"].get)
```

```javascript
const { SecretSpec } = require("secretspec");

const s = SecretSpec.builder()
  .withProvider("keyring://")
  .withReason("boot").load();
console.log(s.secrets.DATABASE_URL.get());
```

```go
s, _ := secretspec.New().
    WithProvider("keyring://").
    WithReason("boot").Load()
fmt.Println(s.Secrets["DATABASE_URL"].Get())
```

```ruby
s = Secretspec::SecretSpec.builder
      .with_provider("keyring://")
      .with_reason("boot").load
puts s.secrets["DATABASE_URL"].get
```

```haskell
s <- S.load (S.builder
      & S.withProvider "keyring://"
      & S.withReason "boot")
print (S.get =<< Map.lookup "DATABASE_URL" (S.resolvedSecrets s))
```

```rust
secretspec_derive::declare_secrets!("secretspec.toml");

let s = Secrets::builder()
    .with_provider("keyring://")
    .with_reason("boot").load()?;
println!("{}", s.secrets.database_url);
```

--------------------------------

### Example Audit Log Record

Source: https://secretspec.dev/concepts/audit

A sample JSON object representing a single audit event entry.

```json
{
  "v": 1,
  "id": "386987e6-291f-4e8f-a08b-73db9d80897b",
  "ts": "2026-06-04T17:04:00.893Z",
  "session_id": "d59e0f0f-ed2f-456f-a2b6-be25a24b7ec7",
  "seq": 0,
  "action": "get",
  "project": "my-app",
  "profile": "production",
  "key": "DATABASE_URL",
  "provider": "keyring://",
  "outcome": "found",
  "reason": "deploy web frontend",
  "actor": { "user": "alice", "agent": "claude-code", "is_agent": true },
  "version": "0.11.0"
}
```

--------------------------------

### Execute Basic Commands

Source: https://secretspec.dev/providers/gcsm

Commands for setting secrets and importing values from environment files.

```bash
# Set a secret
$ secretspec set DATABASE_URL --provider gcsm://my-gcp-project
Enter value for DATABASE_URL: postgresql://localhost/mydb
✓ Secret 'DATABASE_URL' saved to gcsm (profile: default)


# Import from .env
$ secretspec import dotenv://.env
```

--------------------------------

### Define Secret References

Source: https://secretspec.dev/reference/configuration

Examples of defining secret references within a profile configuration using various providers.

```toml
[profiles.production]
DATABASE_URL = { description = "Postgres DSN", ref = { item = "db", field = "password" }, providers = ["prod_vault"] }
INFRA_TOKEN  = { description = "Infra token", ref = { vault = "Production", item = "infra", field = "token" } }
GITHUB_TOKEN = { description = "GitHub token", ref = { item = "GITHUB_PAT" }, providers = ["env"] }
```

--------------------------------

### Configure Devenv.nix

Source: https://secretspec.dev/quick-start

Add secret references to your devenv.nix file.

```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;
}
```

--------------------------------

### Handling Secret Access Refusal

Source: https://secretspec.dev/blog

Example of the error message returned when a secret is accessed without a required reason.

```bash
$ secretspec run -- npm test
Error: Accessing secrets requires a reason. Provide one with --reason
"<why you are accessing these secrets>", the SECRETSPEC_REASON environment
variable, or Secrets::with_reason() in the SDK. (Policy: require_reason in
[project] of secretspec.toml — defaults to "agents"; set it to false to
disable.)
```

--------------------------------

### Initialize and use pass with secretspec

Source: https://secretspec.dev/providers/pass

Commands for initializing the password store and managing secrets.

```bash
# Initialize password store (first time only)
$ pass init <gpg-key-id>


# Set a secret
$ secretspec set DATABASE_URL
Enter value for DATABASE_URL: postgresql://localhost/mydb


# Run with secrets
$ secretspec run -- npm start
```

--------------------------------

### Verify and Set Secrets

Source: https://secretspec.dev/quick-start

Check configuration status and manually set secret values.

```bash
$ secretspec check
```

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

--------------------------------

### List provider aliases

Source: https://secretspec.dev/reference/cli

Display all user-level provider aliases currently configured.

```bash
secretspec config provider list
```

```bash
$ secretspec config provider list
prod_vault  → onepassword://Production
shared      → onepassword://Shared
env         → env://
```

--------------------------------

### Initialize and resolve secrets

Source: https://secretspec.dev/sdk/nodejs

Use the builder pattern to configure providers and profiles, then load secrets into the environment or access them directly.

```javascript
const { SecretSpec } = require('secretspec');


const resolved = SecretSpec.builder()
  .withProvider('keyring://')
  .withProfile('production')
  .withReason('boot web app')
  .load();


console.log(resolved.provider, resolved.profile);
const db = resolved.secrets.DATABASE_URL;
console.log(db.get());   // the value, or the file path for as_path secrets
resolved.setAsEnv();     // export everything into process.env
```

--------------------------------

### Basic Vault CLI Operations

Source: https://secretspec.dev/providers/vault

Common commands for setting, getting, checking, and running applications with Vault secrets.

```bash
# Set a secret using Vault KV v2
$ secretspec set DATABASE_URL --provider vault://vault.example.com:8200/secret


# Get a secret
$ secretspec get DATABASE_URL --provider vault://vault.example.com:8200/secret


# Check secrets
$ secretspec check --provider vault://vault.example.com:8200/secret


# Run with secrets
$ secretspec run --provider vault://vault.example.com:8200/secret -- npm start
```

--------------------------------

### Build with static linking

Source: https://secretspec.dev/sdk/haskell

Configure the build process to statically link the secretspec-ffi archive and include necessary native dependencies.

```bash
cargo build -p secretspec-ffi
TARGET="$(cargo metadata --no-deps --format-version 1 \
  | grep -o '"target_directory":"[^"]*"' | head -1 | sed 's/.*:"\(.*\)"/\1/')"


# Stage the staticlib alone, and capture its native-static-libs for the linker.
LIBDIR="$(mktemp -d)"
cp "$TARGET/debug/libsecretspec_ffi.a" "$LIBDIR/"
NATIVE_LIBS="$(cargo rustc -q -p secretspec-ffi --crate-type staticlib -- \
  --print native-static-libs 2>&1 | sed -n 's/^note: native-static-libs: //p' | tail -1)"
OPTL=(); for l in $NATIVE_LIBS; do OPTL+=("--ghc-options=-optl$l"); done


cabal build --extra-lib-dirs="$LIBDIR" "${OPTL[@]}"
cabal test  --extra-lib-dirs="$LIBDIR" "${OPTL[@]}"
```

--------------------------------

### Translate 1Password Secret Reference

Source: https://secretspec.dev/providers/onepassword

Example of converting a native 1Password secret reference string into the secretspec ref format.

```toml
# op://Infra/Postgres/connection-url becomes:
DATABASE_URL = { description = "Production DB", ref = { vault = "Infra", item = "Postgres", field = "connection-url" }, providers = ["onepassword://Infra"] }
```

--------------------------------

### Initialize and resolve secrets in Ruby

Source: https://secretspec.dev/sdk/ruby

Use the builder pattern to configure providers and profiles, then load secrets and export them to the environment.

```ruby
require "secretspec"


resolved = Secretspec::SecretSpec.builder
                                 .with_provider("keyring://")
                                 .with_profile("production")
                                 .with_reason("boot web app")
                                 .load


puts resolved.provider, resolved.profile
db = resolved.secrets["DATABASE_URL"]
puts db.get             # the value, or the file path for as_path secrets
resolved.set_as_env!    # export everything into ENV
```

--------------------------------

### Secret Reference Configuration

Source: https://secretspec.dev/providers/vault

Example of defining a secret reference in a configuration file pointing to a specific KV path and field.

```toml
[profiles.production]
DATABASE_URL = { description = "DB", ref = { item = "myapp/config", field = "db_url" }, providers = ["vault://vault.example.com:8200/secret"] }
```

--------------------------------

### Define Secret References

Source: https://secretspec.dev/providers/bws

Example configuration for mapping a secret to a specific BWS key name using the ref field.

```toml
[profiles.production]
DATABASE_URL = { description = "DB", ref = { item = "prod-db-connection" }, providers = ["bws://a9230ec4-5507-4870-b8b5-b3f500587e4c"] }
```

--------------------------------

### Common Keyring usage commands

Source: https://secretspec.dev/providers/keyring

Standard commands for setting, retrieving, and running applications with secrets stored in the keyring.

```bash
# Set a secret
$ secretspec set DATABASE_URL
Enter value for DATABASE_URL: postgresql://localhost/mydb
✓ Secret DATABASE_URL saved to keyring


# Get a secret
$ secretspec get DATABASE_URL
postgresql://localhost/mydb


# Run with secrets
$ secretspec run -- npm start


# Use with profiles
$ secretspec set API_KEY --profile production
$ secretspec run --profile production -- npm start
```

--------------------------------

### secretspec init

Source: https://secretspec.dev/reference/cli

Initializes a new secretspec.toml configuration file by importing secrets from an existing .env file.

```APIDOC
## secretspec init

### Description
Initialize a new `secretspec.toml` configuration file from an existing .env file.

### Options
- **--from** (PATH) - Optional - Path to .env file to import from (default: `.env`)

### Example
`secretspec init --from .env.example`
```

--------------------------------

### Initialize and resolve secrets

Source: https://secretspec.dev/sdk/haskell

Use the builder pattern to configure providers and profiles, then resolve secrets and optionally export them to the environment.

```haskell
import qualified SecretSpec as S
import qualified Data.Map.Strict as Map
import Data.Function ((&))


main :: IO ()
main = do
  resolved <-
    S.load
      ( S.builder
          & S.withProvider "keyring://"
          & S.withProfile "production"
          & S.withReason "boot web app"
      )


  print (S.resolvedProvider resolved, S.resolvedProfile resolved)
  case Map.lookup "DATABASE_URL" (S.resolvedSecrets resolved) of
    Just db -> print (S.get db) -- the value, or the file path for as_path secrets
    Nothing -> pure ()
  S.setAsEnv resolved           -- export everything into the process environment
```

--------------------------------

### CI/CD Authentication with PAT

Source: https://secretspec.dev/providers/protonpass

Commands to create a personal access token and authenticate the CLI in a CI environment.

```bash
# Create a token
$ pass-cli personal-access-token create --name ci --expiration 1y


# Authenticate in CI (store the token as a CI secret)
$ pass-cli login --pat $PROTON_PASS_PAT
$ secretspec run -- deploy
```

--------------------------------

### Audit Log JSON Event Structure

Source: https://secretspec.dev/blog/secretspec-0-12-audit-logs-and-coding-agents

Example of a single JSONL entry representing a secret access event, containing metadata without the secret value.

```json
{
  "v": 1,
  "ts": "2026-06-04T17:04:00.893Z",
  "action": "get",
  "project": "my-app",
  "profile": "production",
  "key": "DATABASE_URL",
  "provider": "keyring://",
  "outcome": "found",
  "reason": "deploy web frontend",
  "actor": { "user": "alice", "agent": "claude-code", "is_agent": true },
  "version": "0.12.0"
}
```

--------------------------------

### Using the as_path Option

Source: https://secretspec.dev/reference/configuration

Configuring secrets to be written to temporary files, returning the file path instead of the secret value.

```toml
[profiles.default]
TLS_CERT = { description = "TLS certificate", as_path = true }
GOOGLE_APPLICATION_CREDENTIALS = { description = "GCP service account", as_path = true }
```

--------------------------------

### Dotenv CLI Usage

Source: https://secretspec.dev/providers/dotenv

Common CLI commands for initializing, setting, and running applications with the Dotenv provider.

```bash
# Initialize from existing .env
$ secretspec init --from .env


# Set a secret
$ secretspec set DATABASE_URL --provider dotenv
Enter value for DATABASE_URL: postgresql://localhost/mydb


# Run with secrets
$ secretspec run --provider dotenv -- npm start


# Use different files for different environments
$ secretspec run --provider dotenv:.env.production -- node server.js
```

--------------------------------

### Initialize SecretSpec

Source: https://secretspec.dev/

Generate a secretspec.toml file from an existing .env file.

```bash
$ secretspec init --from dotenv
```

--------------------------------

### Initialize and run SecretSpec

Source: https://secretspec.dev/

Command-line interface usage for initializing a project from an existing .env file, configuring backends, and running applications with injected secrets.

```bash
# 1. Initialize from existing .env
$ secretspec init --from dotenv
✓ Created secretspec.toml with 5 secrets

# 2. Pick a storage backend (one-time)
$ secretspec config init
✓ Saved to ~/.config/secretspec/config.toml

# 3. Run your app with secrets injected
$ secretspec run --profile production -- npm start
✓ Loaded DATABASE_URL from keyring
✓ Loaded REDIS_URL    from keyring
✓ Generated DB_PASSWORD (32 chars)
✓ Wrote TLS_CERT to /tmp/secretspec-tls-cert
› npm start
```

--------------------------------

### Generate typed schema

Source: https://secretspec.dev/reference/cli

Emit a JSON schema for the manifest and use quicktype to generate language-specific accessors.

```bash
secretspec schema [OPTIONS]
```

```bash
$ secretspec schema | quicktype -s schema --top-level SecretSpec --lang python -o secrets_gen.py
```

```python
from secretspec import SecretSpec
from secrets_gen import SecretSpec as Secrets  # quicktype-generated, typed


resolved = SecretSpec.builder().with_reason("boot").load()
s = Secrets.from_dict(resolved.fields())
print(s.database_url)   # typed str
```

--------------------------------

### Configure Environment Variable Provider

Source: https://secretspec.dev/providers/env

The provider requires no configuration options and can be invoked using various URI formats.

```bash
# All these are equivalent
$ secretspec check --provider env
$ secretspec check --provider env:
$ secretspec check --provider env://
```

--------------------------------

### Project Configuration Structure

Source: https://secretspec.dev/reference/configuration

Defines the core project metadata and access policy settings.

```toml
[project]
name = "my-app"              # Project name (required)
revision = "1.0"             # Format version (required, must be "1.0")
extends = ["../shared"]      # Paths to parent configs for inheritance (optional)
require_reason = "agents"    # When to require a reason for secret access (optional)
```

--------------------------------

### Configure SecretSpec Provider

Source: https://secretspec.dev/

Initialize the configuration to select a default secret provider.

```bash
$ secretspec config init
? Default provider: keyring
```

--------------------------------

### secretspec config init

Source: https://secretspec.dev/reference/cli

Interactively initializes the user-level configuration file.

```APIDOC
## secretspec config init

### Description
Initialize user configuration interactively, setting the preferred provider backend and default profile.
```

--------------------------------

### CI/CD Integration with Service Accounts

Source: https://secretspec.dev/providers/onepassword

Authentication and execution steps for using OnePassword service accounts in automated environments.

```bash
# Set token
$ export OP_SERVICE_ACCOUNT_TOKEN="ops_eyJ..."


# Run command
$ secretspec run --provider onepassword://Production -- deploy
```

--------------------------------

### Select Profiles via CLI and Environment

Source: https://secretspec.dev/concepts/profiles

Resolve the active profile using command-line flags or environment variables.

```bash
# Use specific profile
$ secretspec check --profile development
✓ DATABASE_URL - PostgreSQL connection (using default)
✓ API_KEY - External API key (using default)


# Set via environment
export SECRETSPEC_PROFILE=production
secretspec run -- npm start
```

--------------------------------

### Set secrets with Keyring provider

Source: https://secretspec.dev/providers/keyring

Commands to set secrets using the default keyring storage or a custom folder prefix.

```bash
# Use default keyring storage
$ secretspec set DATABASE_URL --provider keyring


# Custom folder prefix (e.g., to share secrets across projects — see below)
$ secretspec set DATABASE_URL --provider "keyring://shared/{profile}/{key}"
```

--------------------------------

### Dotenv File Format

Source: https://secretspec.dev/providers/dotenv

Standard format for .env files using KEY=VALUE pairs, supporting comments and quoted multi-line strings.

```text
DATABASE_URL=postgresql://localhost/mydb
API_KEY=sk-1234567890
DEBUG=true  # Comments supported


# Multi-line values must be quoted
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"
```

--------------------------------

### Manage User-Level Provider Aliases

Source: https://secretspec.dev/concepts/providers

CLI commands for adding, listing, and removing user-level provider aliases.

```bash

# Add a provider alias
$ secretspec config provider add prod_vault "onepassword://Production"


# List all aliases
$ secretspec config provider list


# Remove an alias
$ secretspec config provider remove prod_vault

```

--------------------------------

### Configure Profile-Level Defaults

Source: https://secretspec.dev/concepts/profiles

Use the [profiles.<name>.defaults] section to apply common settings to all secrets within a profile.

```toml
[providers]
prod_vault = "onepassword://Production"
keyring = "keyring://"


[profiles.production.defaults]
providers = ["prod_vault", "keyring"]
required = true


[profiles.production]
DATABASE_URL = { description = "Production DB" }
API_KEY = { description = "API Key" }
SENTRY_DSN = { description = "Error tracking" }
```

--------------------------------

### Add provider alias

Source: https://secretspec.dev/reference/cli

Register a new provider alias in the user-level configuration file.

```bash
secretspec config provider add <ALIAS> <URI>
```

```bash
$ secretspec config provider add prod_vault "onepassword://Production"
✓ Provider alias 'prod_vault' saved


$ secretspec config provider add shared "onepassword://Shared"
✓ Provider alias 'shared' saved
```

--------------------------------

### Implement multiple inheritance

Source: https://secretspec.dev/concepts/inheritance

Extending multiple configurations where later entries in the list take precedence over earlier ones.

```toml

[project]
name = "api-service"
extends = ["../../shared/base", "../../shared/database", "../../shared/auth"]

```

--------------------------------

### Basic CLI Commands for OnePassword

Source: https://secretspec.dev/providers/onepassword

Commands for setting, retrieving, and executing processes with secrets stored in OnePassword.

```bash
# Set a secret
$ secretspec set DATABASE_URL
Enter value for DATABASE_URL: postgresql://localhost/mydb
✓ Secret DATABASE_URL saved to OnePassword


# Get a secret
$ secretspec get DATABASE_URL


# Run with secrets
$ secretspec run -- npm start
```

--------------------------------

### Keyring URI Format

Source: https://secretspec.dev/providers/keyring

The URI format for configuring the keyring provider, supporting optional folder prefixes.

```text
keyring://[folder_prefix]
```

--------------------------------

### Configure Vault or OpenBao URI

Source: https://secretspec.dev/reference/providers

Use vault or openbao schemes to connect to KV engines, supporting namespaces, custom mounts, and TLS configuration.

```text
vault://vault.example.com:8200/secret       # KV v2 at "secret" mount
vault://vault.example.com:8200              # Default "secret" mount
vault://ns1@vault.example.com:8200/secret   # With namespace
openbao://bao.internal:8200/secret          # OpenBao server
vault://127.0.0.1:8200/secret?kv=1         # KV v1 engine
vault://127.0.0.1:8200/secret?tls=false    # Disable TLS (dev mode)
```

--------------------------------

### Configure secrets as file paths

Source: https://secretspec.dev/sdk/rust

Define secrets as file paths in the configuration and access them as PathBuf objects.

```toml
[profiles.default]
TLS_CERT = { description = "TLS certificate", as_path = true }
TLS_KEY = { description = "TLS private key", as_path = true, required = false }
```

```rust
secretspec_derive::declare_secrets!("secretspec.toml");


fn main() -> Result<(), Box<dyn std::error::Error>> {
    let validated = Secrets::builder().check()?;


    // Required as_path secrets are PathBuf
    let cert_path: &std::path::PathBuf = &validated.secrets.tls_cert;


    // Optional as_path secrets are Option<PathBuf>
    if let Some(key_path) = &validated.secrets.tls_key {
        println!("Key at: {}", key_path.display());
    }


    // Temporary files are cleaned up when `validated` is dropped
    // To persist files beyond the struct's lifetime:
    let paths = validated.keep_temp_files()?;


    Ok(()) 
}
```

--------------------------------

### Run command with audit reason

Source: https://secretspec.dev/reference/cli

Use the --reason flag to provide an audit trail for secret access, which takes precedence over environment variables.

```bash
$ secretspec run --reason "Deploying web frontend" -- ./deploy.sh
```

--------------------------------

### Configure Providers with URIs

Source: https://secretspec.dev/concepts/providers

Defines default provider settings in TOML format.

```toml

[defaults]
provider = "keyring"
profile = "development"  # optional default profile

```

--------------------------------

### Dotenv URI Syntax

Source: https://secretspec.dev/providers/dotenv

URI patterns for specifying the location of .env files, including default and custom paths.

```text
# Default (.env in current directory)
dotenv


# Custom paths
dotenv:.env.local
dotenv:config/.env
dotenv:/absolute/path/.env
```

--------------------------------

### Execute Commands with Provider URIs

Source: https://secretspec.dev/concepts/providers

Specifies exact provider locations using URIs during command execution.

```bash

# Use a specific OnePassword vault
$ secretspec run --provider "onepassword://Development" -- npm start


# Use a specific dotenv file
$ secretspec run --provider "dotenv:/home/user/work/.env" -- npm test

```
Tokens:
Raw