### Team Onboarding with fnox

Source: https://github.com/jdx/fnox/blob/main/docs/guide/real-world-example.md

A step-by-step guide for new team members to set up their environment, including cloning the repo, installing fnox, generating an age key, and configuring secrets for local development.

```bash
# 1. Clone the repo
git clone https://github.com/myorg/my-api
cd my-api

# 2. Install fnox (via mise)
mise install

# 3. Generate age key
age-keygen -o ~/.config/fnox/age.txt

# 4. Share public key with team
grep "public key:" ~/.config/fnox/age.txt
# Send to team lead to add to fnox.toml recipients

# 5. Set decryption key
echo 'export FNOX_AGE_KEY=$(cat ~/.config/fnox/age.txt | grep "AGE-SECRET-KEY")' >> ~/.bashrc
source ~/.bashrc

# 6. Enable shell integration
echo 'eval "$(fnox activate bash)"' >> ~/.bashrc

# 7. Team lead updates fnox.toml with new recipient
# Then re-encrypts all secrets:
fnox reencrypt -p age

# 8. New team member pulls and runs
git pull
cd my-api
# fnox: +4 DATABASE_URL, JWT_SECRET, STRIPE_KEY, SENDGRID_KEY
npm run dev  # Just works!

```

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

### Age Encryption Setup for fnox

Source: https://context7.com/jdx/fnox/llms.txt

Guides through the setup process for age encryption with fnox, including installation, key generation, and configuration for team workflows.

```bash
# 1. Install age CLI
brew install age  # macOS
sudo apt install age  # Ubuntu/Debian

# 2. Generate age key
mkdir -p ~/.config/fnox
age-keygen -o ~/.config/fnox/age.txt

# 3. Get public key for fnox.toml
grep "public key:" ~/.config/fnox/age.txt
# Output: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# 4. Set decryption key environment variable
export FNOX_AGE_KEY=$(grep "AGE-SECRET-KEY" ~/.config/fnox/age.txt)

# Or use SSH key (no conversion needed)
export FNOX_AGE_KEY_FILE=~/.ssh/id_ed25519
```

```toml
# fnox.toml with team members
[providers.age]
type = "age"
recipients = [
  "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",  # alice
  "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGQs...",  # bob (SSH key)
  "age1xyz..."  # ci-bot
]
```

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

### Install and Run VitePress Docs Locally

Source: https://github.com/jdx/fnox/blob/main/docs/README.md

Commands to install project dependencies, start the VitePress development server, build the documentation for production, and preview the production build.

```bash
npm install
npm run docs:dev
npm run docs:build
npm run docs:preview
```

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

### Age Encryption Setup

Source: https://context7.com/jdx/fnox/llms.txt

Guides through the setup process for age encryption, recommended for development and team workflows.

```APIDOC
## Age Encryption Setup

Complete setup for age encryption, which is recommended for development and team workflows.

### Method
CLI Commands and Configuration File Setup

### Endpoint
N/A

### Steps
1.  **Install age CLI**: Use package managers like `brew` or `apt`.
2.  **Generate age key**: Create a new age key pair and store it securely.
3.  **Get public key**: Extract the public key for use in `fnox.toml`.
4.  **Set decryption key environment variable**: Export the private key as an environment variable (`FNOX_AGE_KEY`) or use a key file (`FNOX_AGE_KEY_FILE`).

### Request Example (Setup Commands)
```bash
# 1. Install age CLI (example for macOS)
brew install age

# 2. Generate age key
mkdir -p ~/.config/fnox
age-keygen -o ~/.config/fnox/age.txt

# 3. Get public key for fnox.toml
grep "public key:" ~/.config/fnox/age.txt
# Output: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# 4. Set decryption key environment variable
export FNOX_AGE_KEY=$(grep "AGE-SECRET-KEY" ~/.config/fnox/age.txt)

# Or use SSH key (no conversion needed)
export FNOX_AGE_KEY_FILE=~/.ssh/id_ed25519
```

### Configuration Example (`fnox.toml`)
```toml
[providers.age]
type = "age"
recipients = [
  "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p",  # alice
  "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGQs...",  # bob (SSH key)
  "age1xyz..."  # ci-bot
]
```

### Response
Successful setup involves generating keys and configuring `fnox.toml` and environment variables.
```

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

### Quick Start: Configure and Use KeePass Provider

Source: https://github.com/jdx/fnox/blob/main/docs/providers/keepass.md

This section provides a quick start guide for setting up and using the KeePass provider. It demonstrates how to set the database password, configure the provider in `fnox.toml`, store a secret, and retrieve it.

```bash
# 1. Set database password
export FNOX_KEEPASS_PASSWORD="your-master-password"

# 2. Configure provider
cat >> fnox.toml << 'EOF'
[providers]
keepass = { type = "keepass", database = "~/secrets.kdbx" }
EOF

# 3. Store a secret
fnox set DATABASE_URL "postgresql://localhost/mydb" --provider keepass

# 4. Retrieve from database
fnox get DATABASE_URL
```

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

### Install and Initialize fnox

Source: https://github.com/jdx/fnox/blob/main/README.md

Demonstrates how to install fnox using mise and initialize it within a project. This sets up the basic structure for managing secrets.

```bash
mise use -g fnox
fnox init
```

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

### GitHub Actions CI/CD Setup with fnox

Source: https://github.com/jdx/fnox/blob/main/docs/guide/real-world-example.md

Configuration for GitHub Actions to automate testing and deployment. It uses 'mise-action' to install fnox and 'fnox exec' to run commands securely, including decrypting secrets using an age key.

```yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v3 # Installs fnox via mise

      # Decrypt dev secrets for testing
      - name: Setup fnox
        env:
          FNOX_AGE_KEY: ${{ secrets.FNOX_AGE_KEY }}
        run: |
          # Use the CI age key to decrypt secrets
          echo "FNOX_AGE_KEY is already set from secrets"

      - name: Run tests
        run: |
          fnox exec -- npm test

  deploy-staging:
    if: github.ref == 'refs/heads/develop'
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v3

      - name: Deploy to staging
        env:
          FNOX_AGE_KEY: ${{ secrets.FNOX_AGE_KEY }}
        run: |
          fnox exec --profile staging -- ./deploy.sh

  deploy-production:
    if: github.ref == 'refs/heads/main'
    needs: test
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v3

      - name: Deploy to production
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: us-east-1
          FNOX_IF_MISSING: error # Fail if any secret is missing
        run: |
          fnox exec --profile production -- ./deploy.sh

```

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

### Install Doppler CLI

Source: https://github.com/jdx/fnox/blob/main/docs/providers/doppler.md

Install the Doppler CLI using Homebrew on macOS or apt on Linux. Alternatively, use mise for installation.

```bash
# macOS
brew install dopplerhq/cli/doppler

# Linux
curl -sLf --retry 3 --tlsv1.2 --proto "=https" 'https://packages.doppler.com/public/cli/gpg.DE2A7741A397C129.key' | sudo gpg --dearmor -o /usr/share/keyrings/doppler-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/doppler-archive-keyring.gpg] https://packages.doppler.com/public/cli/deb/debian any-version main" | sudo tee /etc/apt/sources.list.d/doppler-cli.list
sudo apt-get update && sudo apt-get install -y doppler

# Or install via mise
mise use -g "github:DopplerHQ/cli"
```

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

### Install fnox using mise

Source: https://github.com/jdx/fnox/blob/main/README.md

Installs the fnox tool globally using the mise package manager. This is the recommended installation method for ease of use and management.

```bash
mise use -g fnox
```

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

### Install fnox from Source

Source: https://github.com/jdx/fnox/blob/main/README.md

Installs fnox by cloning the repository and building from source using Cargo. This method allows for the latest development versions.

```bash
git clone https://github.com/jdx/fnox
cd fnox
cargo install --path .
```

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

### Start Vaultwarden and Configure Bitwarden CLI (Bash)

Source: https://github.com/jdx/fnox/blob/main/test/BITWARDEN_TESTING.md

This script starts the local Vaultwarden server and configures the Bitwarden CLI (bw) to use it. It guides the user through initial setup, including accepting self-signed certificates and logging in.

```bash
# 1. Start the local vaultwarden server and configure bw CLI
source ./test/setup-bitwarden-test.sh

# 2. If this is your first time, follow the on-screen instructions to:
#    - Open https://localhost:8080 in your browser (accept self-signed certificate)
#    - Create an account
#    - Login with: bw login
#    - Unlock: export BW_SESSION=$(bw unlock --raw)

# 3. Run the tests
mise run test:bats -- test/bitwarden.bats
```

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

### Use Bitwarden Secrets with fnox

Source: https://github.com/jdx/fnox/blob/main/docs/providers/bitwarden.md

Example commands for unlocking Bitwarden (if not already done) and retrieving secrets using `fnox get` or using secrets in commands with `fnox exec`.

```bash
# Unlock Bitwarden (once per session)
export BW_SESSION=$(bw unlock --raw)
# Or bootstrap: export BW_SESSION=$(fnox get BW_SESSION)

# Get secrets
fnox get DATABASE_PASSWORD

# Run commands
fnox exec -- npm start
```

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

### Install Bitwarden CLI

Source: https://github.com/jdx/fnox/blob/main/docs/providers/bitwarden.md

Instructions for installing the Bitwarden CLI on different operating systems. This is a prerequisite for using Bitwarden with fnox.

```bash
# macOS
brew install bitwarden-cli

# Linux
npm install -g @bitwarden/cli

# Windows
choco install bitwarden-cli
```

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

### GCP IAM Example with Stored Credentials

Source: https://github.com/jdx/fnox/blob/main/docs/leases/gcp-iam.md

Example TOML configuration demonstrating how to use stored credentials (e.g., from 1Password) with the GCP IAM lease backend. It shows how to fetch a service account key file and configure the lease.

```toml
[providers.op]
type = "1password"
vault = "Development"

[secrets]
GOOGLE_APPLICATION_CREDENTIALS = { provider = "op", value = "GCP SA/key file", as_file = true }

[leases.gcp]
type = "gcp-iam"
service_account_email = "my-sa@my-project.iam.gserviceaccount.com"
duration = "1h"
```

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

### Start Vault Dev Server and Run Tests (Bash)

Source: https://github.com/jdx/fnox/blob/main/test/VAULT_TESTING.md

Quick start commands to initialize a local Vault dev server using a helper script and then execute integration tests with Bats. Assumes `mise` is installed for running tests.

```bash
# 1. Start the local Vault dev server
source ./test/setup-vault-test.sh

# 2. Run the tests
mise run test:bats -- test/vault.bats
```

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

### Multi-Environment Configuration with Bitwarden

Source: https://github.com/jdx/fnox/blob/main/docs/providers/bitwarden.md

Example `fnox.toml` demonstrating how to configure different Bitwarden providers for various environments (e.g., development, production) using profiles.

```toml
# Bootstrap session token (encrypted in git)
[providers]
age = { type = "age", recipients = ["age1..."] }
bitwarden = { type = "bitwarden" }

[secrets]
BW_SESSION = { provider = "age", value = "encrypted-session..." }
DATABASE_URL = { provider = "bitwarden", value = "Dev Database" }

# Production: Different Bitwarden organization
[profiles.production.providers]
bitwarden = { type = "bitwarden", organization_id = "prod-org-id" }

[profiles.production.secrets]
DATABASE_URL = { provider = "bitwarden", value = "Prod Database" }
```

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

### fnox Configuration Example

Source: https://github.com/jdx/fnox/blob/main/README.md

An example TOML configuration file for fnox, demonstrating how to set up encryption providers (like 'age') and define secrets, including encrypted values and default local values. It also shows how to configure profiles for different environments like 'production' with cloud providers.

```toml
# fnox.toml

[providers]
age = { type = "age", recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] }

[secrets]
# Development secrets (encrypted in git)
DATABASE_URL = { provider = "age", value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC..." }  # ← encrypted, safe to commit
API_KEY = { default = "dev-key-12345" }  # ← plain default for local dev

[profiles.production.providers]
aws = { type = "aws-sm", region = "us-east-1", prefix = "myapp/" }

[profiles.production.secrets]
DATABASE_URL = { provider = "aws", value = "database-url" }  # ← reference to AWS secret
```

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

### Install Age CLI

Source: https://github.com/jdx/fnox/blob/main/docs/providers/age.md

Instructions for installing the age encryption tool on macOS and Linux systems.

```bash
# macOS
brew install age

# Linux (Ubuntu/Debian)
sudo apt install age
```

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

### Implement Revocation Logic

Source: https://github.com/jdx/fnox/blob/main/docs/leases/command.md

Example scripts for both creating and revoking a lease using a unique lease ID.

```bash
#!/bin/bash
# scripts/get-creds.sh

LEASE_ID="custom-$(date +%s)"
TOKEN=$(my-tool create-token --ttl "$FNOX_LEASE_DURATION")

jq -n \
  --arg token "$TOKEN" \
  --arg id "$LEASE_ID" \
  '{
    credentials: { API_TOKEN: $token },
    lease_id: $id
  }'
```

```bash
#!/bin/bash
# scripts/revoke-creds.sh

my-tool revoke-token "$FNOX_LEASE_ID"
```

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

### Manual Vault Dev Server Setup and Test Execution (Bash)

Source: https://github.com/jdx/fnox/blob/main/test/VAULT_TESTING.md

Manual steps to set up a local Vault dev server using Docker Compose, configure necessary environment variables, verify the connection, and run integration tests. This method provides more control over the setup process.

```bash
# Start Vault dev server
docker compose -f test/docker-compose.vault.yml up -d

# Export environment variables
export VAULT_ADDR="http://localhost:8200"
export VAULT_TOKEN="fnox-test-token"

# Verify connection
vault status

# Run tests
mise run test:bats -- test/vault.bats
```

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

### Define Root Configuration with Providers

Source: https://github.com/jdx/fnox/blob/main/docs/guide/hierarchical-config.md

Example of a root-level configuration file defining encryption providers and shared secrets for a monorepo.

```toml
[providers]
age = { type = "age", recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] }

[secrets]
LOG_LEVEL = { default = "info" }
ENVIRONMENT = { default = "development" }
JWT_SECRET = { provider = "age", value = "encrypted-shared-jwt..." }
```

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

### Bash Command to List GitHub App Installations

Source: https://github.com/jdx/fnox/blob/main/docs/leases/github-app.md

This bash command uses curl to list installations for a GitHub App. It requires authentication using a JSON Web Token (JWT) and demonstrates how to retrieve installation IDs, which are necessary for configuring the github-app lease backend.

```bash
# List installations for your app (requires JWT auth)
curl -H "Authorization: Bearer $JWT" \
  https://api.github.com/app/installations
```

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

### Configure Bitwarden Provider Session (Bash)

Source: https://github.com/jdx/fnox/blob/main/docs/reference/environment.md

Provides an example of setting the BW_SESSION environment variable in Bash for authenticating with the Bitwarden provider in Fnox.

```bash
export BW_SESSION="..."
```

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

### Configure Bitwarden Provider in fnox

Source: https://github.com/jdx/fnox/blob/main/docs/providers/bitwarden.md

Example TOML configuration for setting up the Bitwarden provider in fnox. Optional parameters like collection and organization IDs can be specified.

```toml
[providers]
bitwarden = { type = "bitwarden", collection = "my-collection-id", organization_id = "my-org-id" }
```

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

### Install 1Password CLI on Linux

Source: https://github.com/jdx/fnox/blob/main/docs/providers/1password.md

Provides instructions for installing the 1Password CLI on Linux systems using APT package manager. It involves adding the GPG key and repository.

```bash
# Linux
curl -sS https://downloads.1password.com/linux/keys/1password.asc | \
  sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | \
  sudo tee /etc/apt/sources.list.d/1password.list
sudo apt update && sudo apt install 1password-cli
```

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

### Manually Start Vaultwarden and Configure Bitwarden CLI (Bash)

Source: https://github.com/jdx/fnox/blob/main/test/BITWARDEN_TESTING.md

Provides manual steps to start the Vaultwarden server using Docker Compose, configure the Bitwarden CLI to connect to the local server, and perform login and session export. It highlights the need to accept self-signed certificates.

```bash
# Start vaultwarden
docker compose -f test/docker-compose.bitwarden.yml up -d

# Configure bw CLI to use local server (HTTPS required)
# Note: NODE_TLS_REJECT_UNAUTHORIZED=0 is set by the setup script to allow self-signed certificates
bw config server https://localhost:8080

# Create account via web UI (accept self-signed certificate warning)
open https://localhost:8080

# Login with bw CLI
bw login

# Unlock and export session
export BW_SESSION=$(bw unlock --raw)

# Run tests
 mise run test:bats -- test/bitwarden.bats
```

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

### Example fnox Configuration (TOML)

Source: https://github.com/jdx/fnox/blob/main/docs/guide/how-it-works.md

A comprehensive example of a `fnox.toml` file, showcasing the definition of multiple providers (age and aws-sm) and various secret types including encrypted inline, remote references, and default values.

```toml
# Provider definitions
[providers]
age = { type = "age", recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] }
aws = { type = "aws-sm", region = "us-east-1" }

[secrets]
JWT_SECRET = { provider = "age", value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC4uLg==" }  # Encrypted secret (in git)
DATABASE_URL = { provider = "aws", value = "prod-database-url" }  # Remote secret (in AWS)
NODE_ENV = { default = "development" }  # Default value (fallback)
```

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

### Configure Local Overrides

Source: https://github.com/jdx/fnox/blob/main/docs/guide/hierarchical-config.md

Example of creating a local override file to define machine-specific secrets that should not be committed to version control.

```bash
cat > fnox.local.toml << 'EOF'
[secrets.DATABASE_URL]
default = "postgresql://localhost/mylocal"

[secrets.DEBUG_MODE]
default = "true"
EOF
```

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

### CI/CD Integration (GitHub Actions)

Source: https://context7.com/jdx/fnox/llms.txt

Example of integrating fnox into a GitHub Actions workflow for automated deployments.

```APIDOC
## CI/CD Integration (GitHub Actions)

GitHub Actions workflow example for using fnox in CI/CD pipelines.

### Method
YAML Configuration (GitHub Actions Workflow)

### Endpoint
N/A (Workflow file)

### Workflow Example (`.github/workflows/deploy.yml`)
```yaml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install fnox
        run: |
          curl -fsSL https://mise.run | sh
          mise use -g fnox

      # For age encryption
      - name: Deploy with age-encrypted secrets
        env:
          FNOX_AGE_KEY: ${{ secrets.FNOX_AGE_KEY }}
        run: |
          fnox exec -- ./deploy.sh

      # For AWS Secrets Manager
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Deploy with AWS secrets
        run: |
          fnox exec --profile production -- ./deploy.sh
```

### Description
This workflow demonstrates how to install fnox, and then use `fnox exec` to run deployment scripts (`./deploy.sh`) with secrets managed by either `age` encryption or AWS Secrets Manager. It shows how to pass secrets as environment variables to the workflow and how to configure AWS credentials.

### Parameters (Workflow Context)
- **`secrets.FNOX_AGE_KEY`**: GitHub secret containing the `age` private key for decryption.
- **`secrets.AWS_ACCESS_KEY_ID`**, **`secrets.AWS_SECRET_ACCESS_KEY`**: GitHub secrets for AWS credentials.
- **`--profile production`**: Used with `fnox exec` to specify the `production` profile for fetching secrets.
```

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

### Initialize Hardware-Backed Providers and Secrets

Source: https://github.com/jdx/fnox/blob/main/docs/guide/leases.md

Commands to register a hardware provider and store master credentials securely using the CLI.

```bash
fnox provider add secure yubikey
fnox set AWS_ACCESS_KEY_ID "AKIA..." --provider secure
fnox set AWS_SECRET_ACCESS_KEY "wJalr..." --provider secure
```

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

### Configure Custom Command Lease Backend

Source: https://github.com/jdx/fnox/blob/main/docs/leases/command.md

Example TOML configuration for defining a custom command lease in fnox, specifying the create and revoke scripts.

```toml
[leases.custom]
type = "command"
create_command = "./scripts/get-creds.sh"
revoke_command = "./scripts/revoke-creds.sh"
duration = "1h"
```

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

### Install and Start Secret Service on Ubuntu/Debian

Source: https://github.com/jdx/fnox/blob/main/docs/providers/keychain.md

Shows the commands to install the GNOME Keyring and start the secret service on Ubuntu/Debian-based Linux distributions. This is essential for resolving 'Service not available' errors on these systems.

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

# Or use KWallet
sudo apt-get install kwalletmanager
```

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

### Initialize fnox project

Source: https://github.com/jdx/fnox/blob/main/docs/guide/quick-start.md

Initializes a new fnox configuration in the current directory by creating a fnox.toml file.

```bash
cd your-project
fnox init
```

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

### CI/CD Example with GitHub Actions

Source: https://github.com/jdx/fnox/blob/main/docs/providers/doppler.md

Integrate Doppler secrets into GitHub Actions workflows using FNOX. Ensure the `DOPPLER_TOKEN` is set as a GitHub secret.

```yaml
name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v3

      - name: Deploy
        env:
          DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }}
        run: |
          fnox exec -- ./deploy.sh
```

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

### Interactive Lease Creation for Remote Environments

Source: https://github.com/jdx/fnox/blob/main/docs/guide/leases.md

Demonstrates how to create a lease interactively without storing master credentials on disk, suitable for shared or remote servers.

```bash
fnox lease create aws -i
fnox exec -- aws s3 ls
```

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

### Initialize fnox Project

Source: https://github.com/jdx/fnox/blob/main/docs/guide/real-world-example.md

Initializes a new project with fnox and sets up git version control. This is the first step in managing your project's configuration and secrets.

```bash
cd my-api
fnox init
git init
```

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

### Configure Doppler Provider in FNOX

Source: https://github.com/jdx/fnox/blob/main/docs/providers/doppler.md

Configure the Doppler provider in your fnox.toml file, specifying the project and config. This example shows a basic setup.

```toml
[providers]
doppler = { type = "doppler", project = "my-project", config = "prd" }
```

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

### Quick Start: Azure Key Vault Secrets with FNOX

Source: https://github.com/jdx/fnox/blob/main/docs/providers/azure-sm.md

A step-by-step guide to create an Azure Key Vault, configure the FNOX provider, set a secret, reference it in FNOX, and retrieve it.

```bash
# 1. Create Key Vault
az keyvault create --name "myapp-vault" --resource-group "myapp-rg"

# 2. Configure provider
cat >> fnox.toml << 'EOF'
[providers]
azure = { type = "azure-sm", vault_url = "https://myapp-vault.vault.azure.net/", prefix = "myapp/" }
EOF

# 3. Create secret
az keyvault secret set --vault-name "myapp-vault" --name "myapp-database-url" --value "postgresql://..."

# 4. Reference in fnox
cat >> fnox.toml << 'EOF'
[secrets]
DATABASE_URL = { provider = "azure", value = "database-url" }
EOF

# 5. Get secret
fnox get DATABASE_URL
```

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

### Multi-Environment fnox Configuration with Infisical

Source: https://github.com/jdx/fnox/blob/main/docs/providers/infisical.md

Example of a `fnox.toml` configuration supporting multiple providers, including 'age' for encrypted bootstrap tokens and 'infisical' for secrets. This setup is useful for managing secrets across different environments.

```toml
# Bootstrap token (encrypted in git)
[providers]
age = { type = "age", recipients = ["age1..."] }
infisical = { type = "infisical", project_id = "abc123", environment = "dev", path = "/" }

[secrets]
INFISICAL_TOKEN = { provider = "age", value = "encrypted-token..." }
DATABASE_URL = { provider = "infisical", value = "DATABASE_URL" }
```

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

### Initialize fnox Configuration

Source: https://context7.com/jdx/fnox/llms.txt

Creates a new `fnox.toml` configuration file. Options include skipping the wizard for minimal configuration, initializing a global configuration for machine-wide secrets, and forcing an overwrite of existing configuration.

```bash
# Initialize fnox in current project
fnox init

# Initialize with interactive wizard skipped (minimal config)
fnox init --skip-wizard

# Initialize global config for machine-wide secrets
fnox init --global

# Force overwrite existing configuration
fnox init --force
```

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

### Multi-Environment Configuration with Age and KMS

Source: https://github.com/jdx/fnox/blob/main/docs/providers/aws-kms.md

This TOML example demonstrates a multi-environment setup in fnox, using 'age' encryption for development and AWS KMS for production. It shows how to define different providers for different profiles.

```toml
# Development: age encryption (free)
[providers]
age = { type = "age", recipients = ["age1..."] }

[secrets]
DATABASE_URL = { provider = "age", value = "encrypted-dev..." }

# Production: AWS KMS
[profiles.production.providers]
kms = { type = "aws-kms", key_id = "arn:aws:kms:us-east-1:123456789012:key/...", region = "us-east-1" }

[profiles.production.secrets]
DATABASE_URL = { provider = "kms", value = "AQICAHhw..." }  # ← KMS encrypted ciphertext
```

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

### Quick Start: FNOX GCP Secret Manager Setup

Source: https://github.com/jdx/fnox/blob/main/docs/providers/gcp-sm.md

Enables the Secret Manager API, configures the GCP provider in FNOX, creates a secret, references it in FNOX configuration, and retrieves the secret.

```bash
# 1. Enable Secret Manager API
gcloud services enable secretmanager.googleapis.com

# 2. Configure provider
cat >> fnox.toml << 'EOF'
[providers]
gcp = { type = "gcp-sm", project = "my-project-id", prefix = "myapp/" }
EOF

# 3. Create secret
echo -n "postgresql://..." | gcloud secrets create myapp-database-url --data-file=-

# 4. Reference in fnox
cat >> fnox.toml << 'EOF'
[secrets]
DATABASE_URL = { provider = "gcp", value = "database-url" }
EOF

# 5. Get secret
fnox get DATABASE_URL
```

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

### Quick Start: Azure Key Vault Keys with FNOX

Source: https://github.com/jdx/fnox/blob/main/docs/providers/azure-kms.md

A step-by-step guide to setting up Azure Key Vault, configuring the FNOX provider, and encrypting/decrypting secrets. This involves using Azure CLI commands and modifying the `fnox.toml` configuration file.

```bash
# 1. Create Key Vault with key
az keyvault key create --vault-name "myapp-vault" --name "encryption-key" --protection software

# 2. Configure provider
cat >> fnox.toml << 'EOF'
[providers]
azurekms = { type = "azure-kms", vault_url = "https://myapp-vault.vault.azure.net/", key_name = "encryption-key" }
EOF

# 3. Encrypt a secret
fnox set DATABASE_URL "postgresql://prod.example.com/db" --provider azurekms

# 4. Get secret (decrypts via Azure)
fnox get DATABASE_URL
```

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

### Install fnox using Cargo

Source: https://github.com/jdx/fnox/blob/main/README.md

Installs the fnox tool using Cargo, the Rust package manager. This method is suitable if you have Rust and Cargo installed.

```bash
cargo install fnox
```

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

### Install Infisical CLI

Source: https://github.com/jdx/fnox/blob/main/docs/providers/infisical.md

Installs the Infisical Command Line Interface (CLI) using Homebrew on macOS. Ensure Homebrew is installed before running this command.

```bash
# macOS
brew install infisical/get-cli/infisical
```

```bash
# Linux
curl -1sLf 'https://dl.cloudsmith.io/public/infisical/infisical-cli/setup.deb.sh' | sudo -E bash
sudo apt-get update && sudo apt-get install -y infisical
```

```bash
# Windows
scoop bucket add infisical https://github.com/Infisical/scoop-infisical.git
scoop install infisical
```

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

### fnox init

Source: https://github.com/jdx/fnox/blob/main/docs/cli/init.md

Initializes a new fnox configuration file with support for global settings and interactive or minimal creation modes.

```APIDOC
## fnox init

### Description
Initialize a new fnox configuration file.

### Usage
fnox init [FLAGS]

### Aliases
i

### Flags
- **-f, --force** - Overwrite existing configuration file
- **-g, --global** - Initialize the global config file (~/.config/fnox/config.toml)
- **--skip-wizard** - Skip the interactive wizard and create a minimal config
```

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

### Run Application with fnox

Source: https://github.com/jdx/fnox/blob/main/docs/guide/real-world-example.md

Demonstrates how to run the application using npm, with secrets automatically loaded by fnox. It also shows an explicit way to execute commands using 'fnox exec'.

```bash
cd my-api
npm run dev
```

```bash
fnox exec -- npm run dev
```

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

### Install bws CLI

Source: https://github.com/jdx/fnox/blob/main/docs/providers/bitwarden-sm.md

Provides instructions for installing the Bitwarden Secrets Manager CLI (bws). It mentions that 'mise' automatically installs it when using Fnox, and also provides manual installation commands for macOS using Homebrew and from GitHub releases.

```bash
# macOS
brew install bws

# Or download from GitHub releases
# https://github.com/bitwarden/sdk-sm/releases
```

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

### Check Bitwarden CLI Installation Path

Source: https://github.com/jdx/fnox/blob/main/test/BITWARDEN_TESTING.md

Verifies if the Bitwarden CLI (bw) is installed and accessible in the system's PATH. It shows the expected installation location managed by mise.

```bash
which bw
# Should show: ~/.local/share/mise/installs/bitwarden/*/bw
```

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

### KeePass Provider Example Configuration

Source: https://github.com/jdx/fnox/blob/main/docs/providers/keepass.md

An example `fnox.toml` configuration demonstrating how to set up the KeePass provider for personal password management. It includes the database path and examples of secrets stored within it.

```toml
[providers]
keepass = { type = "keepass", database = "~/Documents/passwords.kdbx" }

[secrets]
GITHUB_TOKEN = { provider = "keepass", value = "github/token" }
NPM_TOKEN = { provider = "keepass", value = "npm/token" }
```

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

### Create Command Interface

Source: https://github.com/jdx/fnox/blob/main/docs/leases/command.md

Details on how the create script is invoked and the expected JSON output format.

```APIDOC
## Create Command Interface

### Description
The script receives environment variables FNOX_LEASE_DURATION and FNOX_LEASE_LABEL. It must output a JSON object to stdout.

### Expected JSON Output
- **credentials** (object) - Required - Key-value map of environment variable names to credential values
- **expires_at** (string) - Optional - RFC3339 timestamp for expiry
- **lease_id** (string) - Optional - Unique identifier for the lease

### Response Example
```json
{
  "credentials": {
    "MY_TOKEN": "tok-abc123",
    "MY_SECRET": "sec-xyz789"
  },
  "expires_at": "2024-01-15T10:00:00Z",
  "lease_id": "my-custom-lease-1"
}
```
```

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

### Configure Google Cloud Provider Credentials (Bash)

Source: https://github.com/jdx/fnox/blob/main/docs/reference/environment.md

Shows how to set the GOOGLE_APPLICATION_CREDENTIALS environment variable in Bash to point to a service account key file, used by Fnox's GCP providers.

```bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
```

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

### Install Vault CLI

Source: https://github.com/jdx/fnox/blob/main/docs/providers/vault.md

Commands to install the HashiCorp Vault CLI on macOS and Linux systems.

```bash
# macOS
brew install vault

# Linux
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install vault
```

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

### Execute Commands with Azure Token

Source: https://github.com/jdx/fnox/blob/main/docs/leases/azure-token.md

Demonstrates how to run commands using the fnox CLI with the configured Azure token lease.

```bash
fnox exec -- az resource list
```

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

### Bats Test Setup and Teardown

Source: https://github.com/jdx/fnox/blob/main/test/README.md

Standard Bats setup and teardown functions for Fnox E2E tests. Includes loading common setup routines and ensuring proper cleanup.

```bash
setup() {
    load 'test_helper/common_setup'
    _common_setup
}

teardown() {
    _common_teardown
}
```

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

### Manage Global Configuration via CLI

Source: https://github.com/jdx/fnox/blob/main/docs/reference/configuration.md

Commands to initialize the global fnox configuration, set secrets, and add providers that apply across all projects.

```bash
# Initialize global config
fnox init --global

# Add secrets to global config
fnox set MY_TOKEN "secret-value" --global

# Add providers to global config
fnox provider add aws aws-sm --global
```

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

### Get a Single Secret with FNOX

Source: https://github.com/jdx/fnox/blob/main/docs/providers/doppler.md

Retrieve a specific secret from Doppler using the `fnox get` command.

```bash
fnox get DATABASE_URL
```

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

### GitHub Actions CI/CD with Infisical and fnox

Source: https://github.com/jdx/fnox/blob/main/docs/providers/infisical.md

Example GitHub Actions workflow demonstrating how to set up Infisical token and use fnox to execute commands within a CI/CD pipeline. It includes steps for checking out code, setting up the Infisical token, and running tests.

```yaml
name: Test
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v3

      - name: Setup Infisical token
        env:
          INFISICAL_TOKEN: ${{ secrets.INFISICAL_TOKEN }}
        run: |
          # Token is already in environment
          echo "Infisical configured"

      - name: Run tests
        env:
          INFISICAL_TOKEN: ${{ secrets.INFISICAL_TOKEN }}
        run: |
          fnox exec -- npm test
```

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

### GCP IAM Setup with gcloud CLI

Source: https://github.com/jdx/fnox/blob/main/docs/leases/gcp-iam.md

Commands to set up IAM permissions and enable the IAM Credentials API for the GCP IAM lease backend. This includes granting the 'Service Account Token Creator' role and enabling the necessary API.

```bash
gcloud iam service-accounts add-iam-policy-binding \
  my-sa@my-project.iam.gserviceaccount.com \
  --member="user:you@example.com" \
  --role="roles/iam.serviceAccountTokenCreator"
```

```bash
gcloud services enable iamcredentials.googleapis.com --project=my-project
```

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

### Install Vault CLI with mise

Source: https://github.com/jdx/fnox/blob/main/test/VAULT_TESTING.md

Command to install the Vault CLI using the mise package manager.

```bash
mise install vault
```

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

### Install 1Password CLI

Source: https://github.com/jdx/fnox/blob/main/docs/providers/1password.md

Installs the 1Password CLI on macOS using Homebrew. This is a prerequisite for using the 1Password provider with fnox.

```bash
# macOS
brew install 1password-cli
```

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

### Setting a global secret with description

Source: https://github.com/jdx/fnox/blob/main/docs/cli/set.md

Demonstrates how to store a secret in the global configuration file with an associated description.

```bash
fnox set API_KEY my-secret-value --global --description "Production API Key"
```

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

### Install Vault CLI on Linux

Source: https://github.com/jdx/fnox/blob/main/test/VAULT_TESTING.md

Commands to download, unzip, and install the Vault CLI binary on a Linux system.

```bash
# Linux
wget https://releases.hashicorp.com/vault/1.15.0/vault_1.15.0_linux_amd64.zip
unzip vault_1.15.0_linux_amd64.zip
sudo mv vault /usr/local/bin/
```

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

### Start Vault Docker Compose

Source: https://github.com/jdx/fnox/blob/main/test/VAULT_TESTING.md

Command to start Vault in detached mode using the specified Docker Compose file.

```bash
docker compose -f test/docker-compose.vault.yml up -d
```

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

### Verify Project and Config Existence

Source: https://github.com/jdx/fnox/blob/main/docs/providers/doppler.md

If you receive 'Could not find project' or 'Could not find config' errors, use these commands to verify that your project and configuration exist within Doppler. Replace 'my-project' with your actual project name.

```bash
doppler projects
doppler configs --project my-project
```

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

### Configure 1Password Provider Token (Bash)

Source: https://github.com/jdx/fnox/blob/main/docs/reference/environment.md

Demonstrates setting the OP_SERVICE_ACCOUNT_TOKEN environment variable in Bash for authentication with the 1Password provider in Fnox.

```bash
export OP_SERVICE_ACCOUNT_TOKEN="ops_..."
```

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

### Start Vaultwarden Docker Compose

Source: https://github.com/jdx/fnox/blob/main/test/BITWARDEN_TESTING.md

Starts the Vaultwarden service using Docker Compose. This is a prerequisite for many Bitwarden CLI operations.

```bash
docker compose -f test/docker-compose.bitwarden.yml up -d
```

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

### Execute with Profile and Flags

Source: https://github.com/jdx/fnox/blob/main/docs/reference/configuration.md

Command line usage to execute a process using a specific profile while optionally ignoring default configurations.

```bash
fnox exec --profile production --no-defaults -- ./deploy.sh
```

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

### Install GPG (GNU Privacy Guard)

Source: https://github.com/jdx/fnox/blob/main/docs/providers/password-store.md

Installs GPG, a prerequisite for password-store, across different operating systems using package managers.

```bash
# macOS
brew install gnupg
```

```bash
# Ubuntu/Debian
sudo apt install gnupg
```

```bash
# Fedora/RHEL
sudo dnf install gnupg2
```

```bash
# Arch
sudo pacman -S gnupg
```

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

### TOML Configuration for GitHub App Lease

Source: https://github.com/jdx/fnox/blob/main/docs/leases/github-app.md

This TOML configuration sets up the github-app lease backend. It specifies the app ID, installation ID, and the path to the private key file. Optional fields like permissions and repositories can be used to scope the generated token.

```toml
[leases.github]
type = "github-app"
app_id = "12345"
installation_id = "67890"
private_key_file = "~/.config/fnox/github-app.pem"
duration = "1h"

[leases.github.permissions]
contents = "read"
pull_requests = "write"
```

```toml
[leases.github]
type = "github-app"
app_id = "12345"
installation_id = "67890"
private_key_file = "~/.config/fnox/github-app.pem"
repositories = ["api", "frontend"]

[leases.github.permissions]
contents = "read"
```

```toml
[leases.github]
type = "github-app"
app_id = "12345"
installation_id = "67890"
private_key_file = "~/.config/fnox/github-app.pem"
```

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

### Install Vault CLI on macOS with Homebrew

Source: https://github.com/jdx/fnox/blob/main/test/VAULT_TESTING.md

Commands to install the Vault CLI on macOS using Homebrew, including tapping the HashiCorp repository.

```bash
# macOS
brew tap hashicorp/tap
brew install hashicorp/tap/vault
```

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

### Install 1Password CLI on Windows

Source: https://github.com/jdx/fnox/blob/main/docs/providers/1password.md

Installs the 1Password CLI on Windows using the Scoop package manager. This is a convenient way to manage CLI tools on Windows.

```bash
# Windows (via Scoop)
scoop install 1password-cli
```

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

### Deploy to Production with fnox

Source: https://github.com/jdx/fnox/blob/main/docs/guide/real-world-example.md

Details the process for deploying to production, ensuring AWS credentials are set and using fnox exec with the production profile. It also configures fnox to fail if any required secrets are missing.

```bash
# Ensure AWS credentials are set
export AWS_REGION=us-east-1

# Deploy to production
fnox exec --profile production -- ./deploy.sh
```

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

### Install Bitwarden SM CLI (bws)

Source: https://github.com/jdx/fnox/blob/main/docs/providers/bitwarden-sm.md

Installs the Bitwarden SM command-line interface (bws) using Homebrew. This is a prerequisite for using the 'bws' commands.

```bash
brew install bws
```