### Example Provider Implementation

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/adding-providers.md

This example demonstrates a complete implementation of a custom provider, including configuration parsing, struct definition, trait implementation, and registration using the `register_provider!` macro.

```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 get(&self, project: &str, key: &str, profile: &str) -> Result<Option<String>> {
        // Implementation
        Ok(None)
    }

    fn set(&self, project: &str, key: &str, value: &str, profile: &str) -> Result<()> {
        // Implementation
        Ok(())
    }
}
```

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

### Basic Secretspec Commands with GCSM

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/gcsm.md

Examples of setting, getting, checking, and running commands using the Google Cloud Secret Manager provider.

```bash
# Set a secret
$ secretspec set DATABASE_URL --provider gcsm://my-gcp-project

# Get a secret
$ secretspec get DATABASE_URL --provider gcsm://my-gcp-project

# Check secrets
$ secretspec check --provider gcsm://my-gcp-project

# Run with secrets
$ secretspec run --provider gcsm://my-gcp-project -- npm start
```

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

### Install gnome-keyring on Fedora

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/keyring.md

Install the gnome-keyring package on Fedora systems.

```bash
# Fedora
$ sudo dnf install gnome-keyring
```

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

### Practical Example: Web Application Profile Configuration

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/profiles.md

A comprehensive example for a web application, defining default secrets and then customizing them for development and production environments. This includes setting defaults for common secrets and adding environment-specific ones.

```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 gnome-keyring on Debian/Ubuntu

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/keyring.md

Install the gnome-keyring package on Debian or Ubuntu systems if it's missing.

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

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

### Complete secretspec.toml Example

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/declarative.md

An example demonstrating project configuration with inheritance and service-specific secret declarations. Includes project metadata and a default profile with inherited and new secrets.

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

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

### Run SecretSpec Example

Source: https://github.com/cachix/secretspec/blob/main/examples/derive/README.md

Execute the SecretSpec code generation example using Cargo.

```bash
# From this directory
cargo run

# Or from the workspace root
cargo run -p codegen-example
```

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

### Complete secretspec.toml Example

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/configuration.md

An example demonstrating project and multiple profile configurations with various secret variable options.

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

# 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 }

```

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

### Install gnome-keyring on Arch

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/keyring.md

Install the gnome-keyring package on Arch Linux systems.

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

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

### Create a New Starlight Project

Source: https://github.com/cachix/secretspec/blob/main/docs/README.md

Use this command to initialize a new project with the Starlight template. Ensure you have Node.js and npm installed.

```bash
npm create astro@latest -- --template starlight
```

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

### Install SecretSpec via Static Binary

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/quick-start.mdx

Use this command to download and install the SecretSpec static binary.

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

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

### as_path Option Example

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/configuration.md

Demonstrates using the `as_path = true` option to write secrets to temporary files.

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

```

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

### Dotenv File Format Example

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/dotenv.md

Demonstrates the standard dotenv format with KEY=VALUE pairs, comments, and multi-line quoted values.

```bash
# .env
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-----"
```

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

### Install SecretSpec via curl

Source: https://github.com/cachix/secretspec/blob/main/README.md

Installs SecretSpec by downloading and executing a script from the official installation URL. Alternative installation methods are available in the documentation.

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

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

### Install Pass Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/pass.md

Install the `pass` package on various Linux distributions and macOS.

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

# Fedora
$ sudo dnf install pass

# Arch
$ sudo pacman -S pass

# macOS
$ brew install pass
```

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

### Multiple Inheritance Example

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/inheritance.md

Demonstrates how a project can extend multiple shared configurations. Later sources in the `extends` list take precedence over earlier ones.

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

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

### Config Inheritance Example

Source: https://github.com/cachix/secretspec/blob/main/CLAUDE.md

Shows how to extend configurations from other files in SecretSpec.

```toml
extends = ["../shared/common"]
```

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

### Per-Secret Provider Configuration Example

Source: https://github.com/cachix/secretspec/blob/main/CLAUDE.md

Demonstrates how to specify providers for individual secrets within the TOML configuration.

```toml
[profiles.production]
DATABASE_URL = { description = "Production DB", providers = ["prod_vault", "keyring"] }
API_KEY = { description = "API Key", providers = ["shared"] }
GITHUB_TOKEN = { description = "GitHub token from env", providers = ["env"] }
```

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

### Install LastPass CLI

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/lastpass.md

Installs the LastPass CLI using package managers for macOS, Linux, or NixOS.

```bash
# macOS
brew install lastpass-cli
```

```bash
# Linux (apt)
sudo apt install lastpass-cli
```

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

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

### CI/CD Setup with Environment Variables

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/awssm.md

Shows how to configure AWS credentials and region using environment variables for CI/CD pipelines when using the AWS Secrets Manager provider.

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

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

### Install SecretSpec with Nix

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/quick-start.mdx

Install SecretSpec using Nix package manager from the unstable channel.

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

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

### Command Line Provider Selection

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/providers.md

Examples of selecting a specific provider directly from the command line using the --provider flag.

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

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

### Run Commands with Providers

Source: https://github.com/cachix/secretspec/blob/main/README.md

Examples of specifying a secret provider for the secretspec run command, including Keyring and dotenv. Also shows how to configure the default provider.

```shell
$ secretspec run --provider keyring -- npm start
$ secretspec run --provider dotenv -- npm start

# Configure default provider
$ secretspec config init
```

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

### Profile Configuration for OnePassword Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/onepassword.md

Example TOML configuration for setting the OnePassword provider for different environments.

```toml
# secretspec.toml
[development]
provider = "onepassword://Development"

[production]
provider = "onepassword://Production"
```

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

### CI/CD with Service Account Token

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/onepassword.md

Example of setting the OnePassword service account token as an environment variable and running a command with the provider.

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

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

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

### Set Secret with Default Vault

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/onepassword.md

Example of setting a secret using the default 'Private' vault.

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

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

### Basic Vault Provider Commands

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/vault.md

Demonstrates basic `secretspec` commands for setting, getting, checking, and running with secrets using the Vault provider.

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

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

### Set Secret with Dotenv Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/dotenv.md

Example of setting a secret using the dotenv provider, which will prompt for the value.

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

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

### Run Commands with Profiles

Source: https://github.com/cachix/secretspec/blob/main/README.md

Examples of using the secretspec run command with specific profiles for development and production environments. Includes initializing the default profile configuration.

```shell
$ secretspec run --profile development -- npm start
$ secretspec run --profile production -- npm start

# Set default profile
$ secretspec config init
```

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

### Set Secret with Specific Account and Vault

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/onepassword.md

Example of setting a secret using a specific account shorthand and vault name.

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

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

### Set Secret with Service Account Token

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/onepassword.md

Example of setting a secret using a service account token for authentication.

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

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

### Initialize SecretSpec Configuration

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/index.mdx

Use this command to interactively set up your default SecretSpec provider and profile. It guides you through selecting a backend like keyring, onepassword, or dotenv.

```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
  lastpass: LastPass password manager
? Select your default profile:
> development
  default
  none
✓ Configuration saved to ~/.config/secretspec/config.toml
```

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

### Set Secret with Specific Vault

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/onepassword.md

Example of setting a secret using a specific vault named 'Production'.

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

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

### Define Application Secrets in secretspec.toml

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/quick-start.mdx

Example `secretspec.toml` file defining project name, revision, and profiles with secret configurations including descriptions, requirements, and default values.

```toml
[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 }
```

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

### SecretSpec TOML Configuration Example

Source: https://github.com/cachix/secretspec/blob/main/README.md

Defines project metadata and declares required secrets with descriptions and defaults in a `secretspec.toml` file. Supports extending other configuration files.

```toml
[project]
name = "my-app"  # Inferred from current directory name when using `secretspec init`
revision = "1.0"
# Optional: extend other configuration files
extends = ["../shared/common", "../shared/auth"]

[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
REDIS_URL = { description = "Redis connection string", required = false, default = "redis://localhost:6379" }
```

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

### Run Command in CI/CD with AWS Secrets Manager

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/awssm.md

Example of running a deployment command in a CI/CD environment using secrets from AWS Secrets Manager, with credentials configured via environment variables.

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

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

### Inject DATABASE_URL into Docker Compose container

Source: https://context7.com/cachix/secretspec/llms.txt

This example shows how to inject the DATABASE_URL from the host's keyring into a Docker Compose container. Ensure the `DATABASE_URL` is defined in your host environment or keyring.

```yaml
services:
  app:
    environment:
      DATABASE_URL: ${DATABASE_URL}
```

```bash
secretspec run -- docker-compose up
```

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

### Vault KV v2 Secret Path Example

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/vault.md

Illustrates the expected KV path for storing secrets with `secretspec` in Vault KV v2.

```plaintext
Example for KV v2: GET /v1/secret/data/secretspec/myapp/production/DATABASE_URL
```

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

### DotEnv Provider URIs

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/providers.md

Examples of URI formats for the DotEnv provider, which stores secrets in .env files. Supports default, custom, and relative paths.

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

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

### List configured provider aliases

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/cli.md

View a list of all provider aliases that have been configured in your SecretSpec setup, along with their corresponding URIs.

```bash
secretspec config provider list
```

```bash
$ secretspec config provider list
```

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

### Get Secret from AWS Secrets Manager

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/awssm.md

Example of retrieving a secret from AWS Secrets Manager using the specified provider and region.

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

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

### Fallback Chain Example in TOML

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/providers.md

Illustrates a fallback chain where SecretSpec attempts to retrieve a secret from 'prod_vault' first, then falls back to 'keyring' if not found.

```toml
# Try OnePassword first, then fall back to keyring if not found
DATABASE_URL = { description = "DB", providers = ["prod_vault", "keyring"] }
```

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

### Initialize user configuration interactively

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/cli.md

Run this command to set up your user configuration interactively. It will prompt you to select a preferred provider backend and a default profile.

```bash
secretspec config init
```

```bash
$ secretspec config init
```

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

### Implement Custom Memory Provider in Rust

Source: https://context7.com/cachix/secretspec/llms.txt

A minimal example of a custom in-memory secret provider implementing the `Provider` trait. It supports `get` and `set` operations and can be instantiated via a URI.

```rust
use secretspec::provider::{Provider, ProviderUrl, ProviderWithPreflight};
use secretspec::{Result, SecretSpecError};
use secrecy::SecretString;
use std::collections::HashMap;

// Minimal example of a custom in-memory provider
pub struct MemoryProvider {
    data: std::sync::Arc<std::sync::RwLock<HashMap<String, String>>>,
}

impl Provider for MemoryProvider {
    fn name(&self) -> &'static str { "memory" }

    fn uri(&self) -> String { "memory://".to_string() }

    fn allows_set(&self) -> bool { true }

    fn get(&self, _project: &str, key: &str, _profile: &str) -> Result<Option<SecretString>> {
        let data = self.data.read().unwrap();
        Ok(data.get(key).map(|v| SecretString::new(v.clone().into())))
    }

    fn set(&self, _project: &str, key: &str, value: &SecretString, _profile: &str) -> Result<()> {
        use secrecy::ExposeSecret;
        let mut data = self.data.write().unwrap();
        data.insert(key.to_string(), value.expose_secret().to_string());
        Ok(())
    }

    // Optional: batch fetch for performance with high-latency providers
    fn get_batch(
        &self,
        project: &str,
        keys: &[&str],
        profile: &str,
    ) -> Result<HashMap<String, SecretString>> {
        let mut results = HashMap::new();
        for key in keys {
            if let Some(value) = self.get(project, key, profile)? {
                results.insert((*key).to_string(), value);
            }
        }
        Ok(results)
    }

    // Optional: reflect all available secrets (used by `secretspec init`)
    fn reflect(&self) -> Result<HashMap<String, secretspec::config::Secret>> {
        Err(SecretSpecError::ProviderOperationFailed(
            "memory provider does not support reflection".to_string(),
        ))
    }
}

```

```rust
use std::convert::TryFrom;

// Built-in providers via URI
let keyring  = Box::<dyn Provider>::try_from("keyring://")?;
let dotenv   = Box::<dyn Provider>::try_from("dotenv://.env.local")?;
let env_prov = Box::<dyn Provider>::try_from("env://")?;
let op       = Box::<dyn Provider>::try_from("onepassword://vault/Production")?;
let vault    = Box::<dyn Provider>::try_from("vault://localhost:8200/secret")?;
let awssm    = Box::<dyn Provider>::try_from("awssm://")?;
let gcsm     = Box::<dyn Provider>::try_from("gcsm://my-gcp-project")?;

if keyring.allows_set() {
    use secrecy::SecretString;
    keyring.set("myapp", "API_KEY", &SecretString::new("secret".into()), "production")?;
}

if let Some(val) = keyring.get("myapp", "API_KEY", "production")? {
    use secrecy::ExposeSecret;
    println!("API_KEY = {}", val.expose_secret());
}

Ok(())

```

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

### LastPass Provider URIs

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/providers.md

Examples of URI formats for the LastPass provider, integrating with LastPass via the lpass CLI. Supports nested folders for organization.

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

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

### Run Application with SecretSpec

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/cli.md

Executes your application using SecretSpec to manage secrets. This command ensures your application starts with the correct secrets loaded.

```bash
# Run your application
$ secretspec run -- npm start
```

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

### Enter Development Environment

Source: https://github.com/cachix/secretspec/blob/main/CLAUDE.md

Use this command to enter the development environment for the project.

```bash
# Enter development environment
devenv shell
```

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

### Set Secret with SDK Default Credentials

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/awssm.md

Example of setting a secret using the AWS Secrets Manager provider with default SDK credentials and a specified region.

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

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

### Use SDK Defaults for AWS Secrets Manager Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/awssm.md

Example of setting a secret using the AWS Secrets Manager provider, relying on SDK defaults for both profile and region.

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

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

### Define Default and Environment-Specific Profiles

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/profiles.md

Define default secret requirements and override them for development and production environments. This example shows how to set required secrets in `default` and then provide optional values or defaults for `development` and add new secrets for `production`.

```toml
[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection", required = true }
API_KEY = { description = "External API key", required = true }

[profiles.development]
# Inherits DATABASE_URL and API_KEY from default, only overriding their requirements
DATABASE_URL = { required = false, default = "postgresql://localhost:5432/myapp_dev" }
API_KEY = { required = false, default = "dev-key-12345" }
DEBUG = { description = "Enable debug mode", required = false, default = "true" }

[profiles.production]
# Inherits all secrets from default profile
# Only need to add production-specific secrets
SENTRY_DSN = { description = "Error tracking", required = true }
```

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

### Starlight Project Structure Overview

Source: https://github.com/cachix/secretspec/blob/main/docs/README.md

Understand the default directory layout for a Starlight project. Markdown and MDX files for documentation should be placed in `src/content/docs/`.

```bash
.\n├── public/\n├── src/\n│   ├── assets/\n│   ├── content/\n│   │   ├── docs/\n│   └── content.config.ts\n├── astro.config.mjs\n├── package.json\n└── tsconfig.json
```

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

### Advanced Secret Generation Options

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/generation.md

Demonstrates various secret generation configurations including custom password lengths and character sets, specific byte lengths for base64 encoding, and different bit sizes for RSA private keys. Also shows an example of an informational-only type.

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

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

### Initialize secretspec from .env.example

Source: https://context7.com/cachix/secretspec/llms.txt

Initializes a secretspec.toml file by importing secret names from an existing .env.example file. Review and adjust the generated secretspec.toml before importing secret values.

```bash
$ secretspec init --from .env.example
✓ Created secretspec.toml with 5 secrets
```

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

### Configure Secret Generation in TOML

Source: https://context7.com/cachix/secretspec/llms.txt

Examples of `secretspec.toml` configurations for auto-generating various types of secrets, including passwords, tokens, keys, and command outputs. Generation is idempotent and respects existing secrets.

```toml
# secretspec.toml — generation examples
[profiles.default]
# 32-char alphanumeric password (default)
DB_PASSWORD   = { description = "Database password",  type = "password",       generate = true }

# Custom length and ASCII charset
ADMIN_PASS    = { description = "Admin password",     type = "password",       generate = { length = 64, charset = "ascii" } }

# 64 lowercase hex chars (32 random bytes)
API_TOKEN     = { description = "API token",          type = "hex",            generate = { bytes = 32 } }

# Base64-encoded random bytes (88 chars for 64 bytes)
SESSION_KEY   = { description = "Session signing key",type = "base64",         generate = { bytes = 64 } }

# UUID v4 (e.g., "550e8400-e29b-41d4-a716-446655440000")
REQUEST_ID    = { description = "Trace ID prefix",    type = "uuid",           generate = true }

# Output of a shell command
MONGO_KEY     = { description = "MongoDB keyfile",    type = "command",        generate = { command = "openssl rand -base64 765" } }

# 2048-bit RSA private key in PKCS1 PEM format
JWT_SIGN_KEY  = { description = "JWT signing key",    type = "rsa_private_key",generate = true }

# Custom bit length RSA key
JWT_SIGN_4096 = { description = "Strong JWT key",     type = "rsa_private_key",generate = { bits = 4096 } }

```

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

### Initialize secretspec.toml from .env file

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/cli.md

Use this command to create a new secretspec.toml configuration file by importing secrets from an existing .env file. Specify the path to the .env file using the --from option.

```bash
secretspec init [OPTIONS]
```

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

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

### Initialize User Configuration

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/cli.md

Sets up the necessary user configuration for SecretSpec. This command should be run after initialization.

```bash
# Set up user configuration
$ secretspec config init
```

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

### Secrets::set() / Secrets::get()

Source: https://context7.com/cachix/secretspec/llms.txt

Provides programmatic get and set operations for individual secrets. `set` accepts an optional value or prompts securely via stdin when called interactively. `get` prints the value to stdout.

```APIDOC
## `Secrets::set()` / `Secrets::get()` — Library: CRUD operations

Programmatic get and set for individual secrets. `set` accepts an optional value or prompts securely via stdin when called interactively. `get` prints the value (or temp-file path for `as_path` secrets) to stdout.

```rust
use secretspec::Secrets;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut spec = Secrets::load()?;
    spec.set_provider("keyring");
    spec.set_profile("development");

    // Set a secret programmatically
    spec.set("DATABASE_URL", Some("postgres://localhost/mydb".to_string()))?;
    // Set interactively (prompts if None and stdin is a terminal)
    spec.set("API_KEY", None)?;

    // Retrieve and print to stdout
    spec.get("DATABASE_URL")?;

    Ok(())
}
```
```

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

### Get a Secret

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/onepassword.md

Shows the command to retrieve a previously set secret.

```bash
# Get a secret
$ secretspec get DATABASE_URL
```

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

### Get Secret from LastPass Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/lastpass.md

Retrieves a secret from the LastPass provider.

```bash
# Get a secret
secretspec get DATABASE_URL --provider lastpass
```

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

### Initialize secretspec.toml with CLI

Source: https://context7.com/cachix/secretspec/llms.txt

Bootstrap a new `secretspec.toml` file in the current directory using the `secretspec init` command. Optionally imports existing secrets from a `.env` file.

```bash
# Create an empty secretspec.toml
$ secretspec init
✓ Created secretspec.toml with 0 secrets

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

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

### Initialize and Use Pass Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/pass.md

Initialize the password store with a GPG key, set secrets using `secretspec set`, and run applications with secrets using `secretspec run`.

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

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

### Dotenv Configuration URI Syntax

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/dotenv.md

Shows how to configure the dotenv provider using URI syntax for default or custom file paths.

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

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

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

### Get Secret with OnePassword Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/providers.md

Retrieve a secret using the OnePassword provider. Supports specifying the account and vault.

```bash
secretspec get API_KEY --provider onepassword://vault
```

```bash
secretspec get API_KEY --provider "onepassword://account@vault"
```

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

### Run Application with Specific .env File

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/dotenv.md

Demonstrates running an application with secrets from a specific .env file for different environments.

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

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

### Get Secret with Dotenv Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/providers.md

Retrieve a secret using the dotenv provider, specifying the path to the .env file.

```bash
secretspec get API_KEY --provider dotenv:/path/to/.env
```

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

### Initialize global secretspec configuration

Source: https://context7.com/cachix/secretspec/llms.txt

Interactively sets up the global secretspec configuration file. Selects the default provider backend and profile. This configuration is not committed to version control.

```bash
$ secretspec config init
? Select your preferred provider backend:
> keyring: Uses system keychain (Recommended)
  dotenv: Traditional .env files
  env: Read-only environment variables
  onepassword: OnePassword password manager (e.g., onepassword://vault)
  lastpass: LastPass password manager
  gcsm: Google Cloud Secret Manager
  awssm: AWS Secrets Manager
  vault: HashiCorp Vault / OpenBao
  bws: Bitwarden Secrets Manager
? Select your default profile:
> development
  default
  none
✓ Configuration saved to /home/user/.config/secretspec/config.toml
```

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

### Get a Secret using Keyring

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/keyring.md

Retrieve a secret stored in the system's keyring using the secretspec CLI.

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

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

### Configure Environment Variable Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/env.md

The env provider accepts no configuration options. These commands show equivalent ways to specify the provider.

```bash
$ secretspec check --provider env
$ secretspec check --provider env:
$ secretspec check --provider env://
```

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

### Get a Secret from BWS

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/bws.md

Command to retrieve a secret from Bitwarden Secrets Manager. Requires the BWS_ACCESS_TOKEN environment variable.

```bash
# Get a secret
$ secretspec get DATABASE_URL --provider bws://a9230ec4-5507-4870-b8b5-b3f500587e4c
```

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

### Vault Provider Authentication via Environment Variable

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/vault.md

Demonstrates setting the Vault token via the `VAULT_TOKEN` environment variable for authentication.

```bash
# Set token via environment
$ export VAULT_TOKEN=hvs.your-token-here
$ secretspec run --provider vault://vault.example.com:8200 -- npm start
```

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

### List Provider Aliases CLI

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/configuration.md

Command to list all configured provider aliases.

```bash
# List all aliases
$ secretspec config provider list

```

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

### Integrate secretspec with GitHub Actions

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/env.md

This example shows how to pass environment variables to secretspec within a GitHub Actions workflow.

```yaml
# GitHub Actions
- name: Run with secrets
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
    API_KEY: ${{ secrets.API_KEY }}
  run: |
    secretspec run --provider env -- npm run deploy
```

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

### Get a secret value

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/cli.md

Retrieve the value of a specific secret by its name. You can optionally specify the provider and profile to use for retrieval.

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

```bash
$ secretspec get DATABASE_URL --profile production
```

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

### Environment Provider URI

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/providers.md

The URI for the Environment provider, which offers read-only access to system environment variables. No setup is required.

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

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

### Initialize Secretspec from .env

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/dotenv.md

Command to initialize secretspec using an existing .env file.

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

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

### SecretSpec CLI Initialization Commands

Source: https://github.com/cachix/secretspec/blob/main/README.md

Commands for initializing and configuring SecretSpec, including creating the secretspec.toml file and setting up user configuration.

```bash
# Initialize and configure
secretspec init                    # Create secretspec.toml
secretspec config init            # Set up user configuration
```

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

### Set a Secret

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/onepassword.md

Demonstrates how to set a secret by interactively entering its value.

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

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

### SecretSpec CLI Run Command

Source: https://github.com/cachix/secretspec/blob/main/README.md

Example of using the secretspec run command to execute another command with secrets injected as environment variables.

```bash
# Run with secrets
secretspec run -- command        # Run command with secrets as env vars
```

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

### Initialize secretspec.toml

Source: https://github.com/cachix/secretspec/blob/main/README.md

Initializes the `secretspec.toml` file by discovering secrets from existing `.env` files. This is the first step in setting up SecretSpec for a project.

```shell
# 1. Initialize secretspec.toml (discovers secrets from .env)
$ 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
```

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

### Project Configuration

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/configuration.md

Defines project metadata like name, revision, and inheritance paths.

```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)

```

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

### Access Pass Secrets

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/pass.md

Secrets are stored in the `pass` store under the path `secretspec/{project}/{profile}/{key}`. This example shows how to retrieve a secret.

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

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

### OpenBao Provider Check Command

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/vault.md

Illustrates checking secrets using the `secretspec` command with the OpenBao provider.

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

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

### Define Profile-Specific Secrets

Source: https://github.com/cachix/secretspec/blob/main/README.md

Example TOML configuration defining secrets for development and production profiles. Development secrets have defaults, while production secrets are required.

```toml
[profiles.development]
DATABASE_URL = { description = "PostgreSQL connection string", required = false, default = "sqlite://./dev.db" }
REDIS_URL = { description = "Redis connection string", required = false, default = "redis://localhost:6379" }

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

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

### LastPass Authentication Methods

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/lastpass.md

Demonstrates LastPass CLI authentication, including standard login, trusting a device, and CI/CD environments.

```bash
# Standard login
lpass login your-email@example.com
```

```bash
# Trust device (reduces MFA prompts)
lpass login --trust your-email@example.com
```

```bash
# CI/CD environments
export LPASS_DISABLE_PINENTRY=1
echo "password" | lpass login --trust your-email@example.com
```

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

### Get a specific secret value

Source: https://context7.com/cachix/secretspec/llms.txt

Retrieves a secret value from a specified profile and provider. Can also print a temporary file path containing the secret.

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

```bash
# as_path secret: prints a temp file path containing the value
$ secretspec get TLS_CERT
/tmp/.tmp1a2b3c4d
```

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

### Use Provider-Specific URIs for Configuration

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/providers.md

Configure providers with specific URIs to target particular vaults, files, or configurations.

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

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

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

### SecretSpec CLI Secret Management Commands

Source: https://github.com/cachix/secretspec/blob/main/README.md

Common commands for managing secrets with SecretSpec, such as checking, setting, getting, and importing secrets from different providers.

```bash
# Manage secrets
secretspec check                  # Verify all secrets are set
secretspec set KEY               # Set a secret interactively
secretspec get KEY               # Retrieve a secret
secretspec import PROVIDER       # Import secrets from another provider
```

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

### Select Profiles via CLI and Environment Variables

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/profiles.md

Demonstrates how to use the `secretspec` command-line tool to check or run with a specific profile. Profiles can be selected using the `--profile` flag or by setting the `SECRETSPEC_PROFILE` environment variable.

```bash
# Use specific profile
$ secretspec check --profile development

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

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

### Import Secrets from .env with BWS

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/bws.md

Import secrets from a .env file into Bitwarden Secrets Manager. Ensure BWS_ACCESS_TOKEN is configured.

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

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

### Dotenv Configuration via Environment Variable

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/dotenv.md

Illustrates setting the secretspec provider to dotenv using an environment variable.

```bash
export SECRETSPEC_PROVIDER=dotenv:.env.local
```

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

### Project Extending Shared Configuration

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/inheritance.md

Extends a shared configuration and overrides existing secrets or adds new ones. This example overrides `DATABASE_URL` and adds `API_KEY`.

```toml
# myapp/secretspec.toml
[project]
name = "myapp"
extends = ["../shared/common"]

[profiles.default]
DATABASE_URL = { description = "MyApp database", required = true }  # Override
API_KEY = { description = "External API key", required = true }     # Add new
```

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

### Vault Provider with Default Mount

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/vault.md

Shows how to set a secret using the Vault provider with the default KV mount path (`secret`).

```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)
```

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

### Provider Trait Definition

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/adding-providers.md

All custom providers must implement this trait, which defines methods for getting and setting secrets, and an optional method for checking if setting is allowed.

```rust
pub trait Provider: Send + Sync {
    fn name(&self) -> &'static str;
    fn get(&self, project: &str, key: &str, profile: &str) -> Result<Option<String>>;
    fn set(&self, project: &str, key: &str, value: &str, profile: &str) -> Result<()>;
    fn allows_set(&self) -> bool { true }  // Optional, defaults to true
}
```

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

### Format Code and Run Linter

Source: https://github.com/cachix/secretspec/blob/main/CLAUDE.md

Applies code formatting and runs linters using pre-commit hooks.

```bash
# Format code / Run linter
pre-commit run -a
```

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

### Vault Provider with Custom Mount

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/vault.md

Demonstrates setting a secret using the Vault provider with a custom KV engine mount path.

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

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

### Get a secret value

Source: https://context7.com/cachix/secretspec/llms.txt

Retrieves a single named secret from the provider and prints its value to standard output. Falls back to a configured default value if the secret is not present.

```bash
$ secretspec get DATABASE_URL
postgresql://localhost/myapp
```

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

### Apply Profile-Level Defaults for Common Settings

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/concepts/profiles.md

Utilize the `profiles.<name>.defaults` section to set common configurations like providers, requirements, or default values for multiple secrets within a profile. This reduces repetition when secrets share similar settings.

```toml
[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" }
```

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

### Starlight Project Commands

Source: https://github.com/cachix/secretspec/blob/main/docs/README.md

Common npm commands for managing your Starlight project. Run these from the project's root directory.

```bash
npm install
```

```bash
npm run dev
```

```bash
npm run build
```

```bash
npm run preview
```

```bash
npm run astro ...
```

```bash
npm run astro -- --help
```

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

### Configure SecretSpec Provider Backend

Source: https://github.com/cachix/secretspec/blob/main/README.md

Sets up the user's preferred provider backend and default profile for SecretSpec. This configuration is saved to `~/.config/secretspec/config.toml`.

```shell
# 2. Set up provider backend
$ secretspec config init
? Select your preferred provider backend:
> onepassword: OnePassword password manager
  dotenv: Traditional .env files
  env: Read-only environment variables
  gcsm: Google Cloud Secret Manager
  keyring: Uses system keychain (Recommended)
  lastpass: LastPass password manager
  pass: Unix password manager (GPG)
? Select your default profile:
> development
  default
  none
✓ Configuration saved to /home/user/.config/secretspec/config.toml
```

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

### Run a Command with Keyring Secrets

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/keyring.md

Execute a command, injecting secrets stored in the keyring.

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

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

### AWS Secrets Manager Provider URIs

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/reference/providers.md

Examples of URI formats for the AWS Secrets Manager provider, storing secrets in AWS Secrets Manager. Supports specific profiles and regions.

```bash
awssm://us-east-1             # Specific AWS region
awssm://production@us-east-1  # Specific AWS profile and region
awssm://                      # SDK default region and credentials
```

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

### Configure Keyring Provider

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/keyring.md

Configure the Keyring provider in your secretspec.toml file, specifying the project name and provider type.

```toml
# secretspec.toml
[project]
name = "myapp"

[[providers]]
type = "keyring"
uri = "keyring://"
```

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

### Vault Provider with Namespace

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/providers/vault.md

Demonstrates using Vault namespaces with the `secretspec` provider, both in the URI and via an environment variable.

```bash
# Using namespace in URI
$ secretspec check --provider vault://team-a@vault.example.com:8200/secret

# Or via environment variable
$ export VAULT_NAMESPACE=team-a
$ secretspec check --provider vault://vault.example.com:8200/secret
```

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

### CRUD Operations for Secrets

Source: https://context7.com/cachix/secretspec/llms.txt

Manage individual secrets using `Secrets::set()` and `Secrets::get()`. `set` can take an optional value or prompt interactively. `get` prints the secret value or temp-file path to stdout.

```rust
use secretspec::Secrets;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut spec = Secrets::load()?;
    spec.set_provider("keyring");
    spec.set_profile("development");

    // Set a secret programmatically
    spec.set("DATABASE_URL", Some("postgres://localhost/mydb".to_string()))?;
    // Set interactively (prompts if None and stdin is a terminal)
    spec.set("API_KEY", None)?;

    // Retrieve and print to stdout
    spec.get("DATABASE_URL")?;

    Ok(())
}
```

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

### Configure Devenv.sh for SecretSpec

Source: https://github.com/cachix/secretspec/blob/main/docs/src/content/docs/quick-start.mdx

Add this configuration to your `devenv.nix` file to automatically populate secrets from SecretSpec.

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