fnox

https://fnox.jdx.dev
Admin
fnox is a secrets management CLI tool that supports multiple providers including encryption methods...
Tokens:74,225
Snippets:703
Trust Score:7.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Quick Start: AWS Parameter Store Setup with fnox

Source: https://fnox.jdx.dev/providers/aws-ps.html

A step-by-step guide to quickly set up AWS Parameter Store integration with fnox, covering provider configuration, parameter creation, and secret referencing.

```bash
# 1. Configure provider in fnox.toml
cat >> fnox.toml << 'EOF'
[providers]
ps = { type = "aws-ps", region = "us-east-1", prefix = "/myapp/prod/" }
EOF

# 2. Create parameter in AWS
aws ssm put-parameter \
  --name "/myapp/prod/database-url" \
  --value "postgresql://prod.example.com/db" \
  --type "SecureString"

# 3. Reference in fnox.toml
cat >> fnox.toml << 'EOF'
[secrets]
DATABASE_URL = { provider = "ps", value = "database-url" }  # With prefix, fetches "/myapp/prod/database-url"
EOF

# 4. Fetch secret
fnox get DATABASE_URL
```

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

### Example fnox.toml Configurations

Source: https://fnox.jdx.dev/providers/keychain.html

Provides various example fnox.toml configurations demonstrating different setups for using the keychain provider, including personal projects, bootstrap tokens, and machine-specific secrets.

```toml
# Personal Project
[providers]
keychain = { type = "keychain", service = "myapp" }

[secrets]
DATABASE_URL = { provider = "keychain", value = "database-url" }
API_KEY = { provider = "keychain", value = "api-key" }
```

```toml
# Bootstrap Tokens
[providers]
keychain = { type = "keychain", service = "fnox-tokens" }

[secrets]
GITHUB_TOKEN = { provider = "keychain", value = "github" }
NPM_TOKEN = { provider = "keychain", value = "npm" }
```

```toml
# Machine-Specific Secrets
# fnox.local.toml (gitignored)
[providers]
keychain = { type = "keychain", service = "fnox-local" }

[secrets]
LAPTOP_DB_URL = { provider = "keychain", value = "laptop-db" }
```

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

### Examples

Source: https://fnox.jdx.dev/leases/command.html

Various examples demonstrating how to use the custom command lease backend.

```APIDOC
## Examples

### Basic Script Example

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

# Call your internal API
RESPONSE=$(curl -s https://creds.internal/api/token \
  --header "Authorization: Bearer $INTERNAL_AUTH" \
  --data "ttl=$FNOX_LEASE_DURATION")

# Output JSON
echo "$RESPONSE"
```

### Generate JSON from CLI output with jq

bash
```bash
#!/bin/bash
# scripts/get-k8s-token.sh

TOKEN=$(kubectl create token my-service-account \
  --duration=\"${FNOX_LEASE_DURATION}s\" 2>/dev/null)

EXPIRY=$(date -u -d \"+$FNOX_LEASE_DURATION seconds\" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
  || date -u -v+${FNOX_LEASE_DURATION}S +%Y-%m-%dT%H:%M:%SZ)

jq -n \
  --arg token "$TOKEN" \
  --arg exp "$EXPIRY" \
  '{ 
    credentials: { KUBE_TOKEN: $token },
    expires_at: $exp
  }'
```

toml
```toml
[leases.k8s]
type = "command"
create_command = "./scripts/get-k8s-token.sh"
duration = "1h"
```

### With Revocation

bash
```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
```bash
#!/bin/bash
# scripts/revoke-creds.sh

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

### Wrapping `aws sts` Directly

bash
```bash
#!/bin/bash
# scripts/assume-role.sh

aws sts assume-role \
  --role-arn "arn:aws:iam::123456789012:role/my-role" \
  --role-session-name "$FNOX_LEASE_LABEL" \
  --duration-seconds "$FNOX_LEASE_DURATION" \
| jq '{ 
    credentials: {
      AWS_ACCESS_KEY_ID: .Credentials.AccessKeyId,
      AWS_SECRET_ACCESS_KEY: .Credentials.SecretAccessKey,
      AWS_SESSION_TOKEN: .Credentials.SessionToken
    },
    expires_at: .Credentials.Expiration
  }'
```

### Parsing Key=Value Output

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

# Some tools output key=value pairs
OUTPUT=$(my-tool get-creds --format=env)

# Parse into JSON with jq
echo "$OUTPUT" | jq -Rn '
  [inputs | split("=") | {(.[0]): .[1]}] | add |
  { credentials: . }
'
```
```

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

### Example Configurations

Source: https://fnox.jdx.dev/leases/github-app.html

Provides various examples of how to configure the GitHub App lease backend for different use cases.

```APIDOC
## Example Configurations

### Description
This section provides practical examples of how to configure the `github-app` lease backend for different scenarios, including minimal setup, scoped permissions, scoped repositories, using stored private keys, custom environment variables, and GitHub Enterprise.

### Minimal Configuration

This configuration uses the essential parameters to obtain a token with all available permissions and repository access for the installation.

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

**Usage Example:**
```bash
fnox exec -- gh pr list
```

### Scoped to Specific Permissions

Configure the token to have read access to contents and write access to pull requests and issues.

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

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

### Scoped to Specific Repositories

Limit the token's access to only the `api` and `frontend` repositories, with read access to contents.

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

### With Stored Private Key

Store the private key in a secret provider (e.g., 1Password) and reference it via an environment variable.

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

[secrets]
FNOX_GITHUB_APP_PRIVATE_KEY = { provider = "op", value = "GitHub App/private key" }

[leases.github]
type = "github-app"
app_id = "12345"
installation_id = "67890"
```

*fnox resolves the secret first, then the lease backend picks it up from the environment.*

### Custom Environment Variable

Use a custom environment variable name (`GH_TOKEN`) for the generated token.

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

### GitHub Enterprise

Configure the `api_base` to point to your GitHub Enterprise instance.

```toml
[leases.github]
type = "github-app"
app_id = "12345"
installation_id = "67890"
private_key_file = "~/.config/fnox/github-app.pem"
api_base = "https://github.example.com/api/v3"
```
```

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

### Initial Setup for Hardware-Backed Providers

Source: https://fnox.jdx.dev/guide/leases.html

These bash commands demonstrate the initial setup for hardware-backed credential providers in fnox. It covers adding a 'secure' provider using either 'yubikey' or 'fido2' and then setting master credentials like AWS access keys, requiring a physical key tap for security.

```bash
# 1. Create the hardware-backed provider (choose one)
fnox provider add secure yubikey    # YubiKey HMAC-SHA1
fnox provider add secure fido2      # Any FIDO2 key

# 2. Store your master credentials (requires key tap)
fnox set AWS_ACCESS_KEY_ID "AKIA..." --provider secure
fnox set AWS_SECRET_ACCESS_KEY "wJalr..." --provider secure
```

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

### Example KeePass Configurations

Source: https://fnox.jdx.dev/providers/keepass.html

Presents two example `fnox.toml` configurations demonstrating how to set up the KeePass provider for different use cases: a personal password database and a project-specific database.

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

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

```toml
# Project-Specific Database
[providers]
keepass = { type = "keepass", database = "./secrets.kdbx" }

[secrets]
DATABASE_URL = { provider = "keepass", value = "database" }
API_KEY = { provider = "keepass", value = "api-key" }
```

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

### CI/CD Integration Example (GitHub Actions)

Source: https://fnox.jdx.dev/providers/bitwarden-sm.html

This snippet demonstrates how to integrate FNOX and Bitwarden Secrets Manager into a GitHub Actions workflow. It shows how to check out code, set up `mise` (which installs `bws`), and then use `fnox exec` to run deployment scripts with secrets securely loaded.

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

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

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

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

### Complete fnox.toml Example

Source: https://fnox.jdx.dev/guide/how-it-works.html

A comprehensive example showing multiple providers, inline encrypted secrets, remote references, and default fallback values in a single configuration file.

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

[secrets]
JWT_SECRET = { provider = "age", value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC4uLg==" }
DATABASE_URL = { provider = "aws", value = "prod-database-url" }
NODE_ENV = { default = "development" }
```

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

### CI/CD Example with Fnox Profiles (YAML)

Source: https://fnox.jdx.dev/guide/profiles.html

Provides a GitHub Actions workflow example demonstrating how to use Fnox profiles within CI/CD pipelines. It shows separate jobs for deploying to staging and production environments, each specifying the appropriate Fnox profile.

```yaml
# .github/workflows/deploy.yml
jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    steps:
      - run: fnox exec --profile staging -- ./deploy.sh

  deploy-production:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - run: fnox exec --profile production -- ./deploy.sh
```

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

### Bootstrap Command Example

Source: https://fnox.jdx.dev/providers/keychain.html

An example of bootstrapping by exporting a secret retrieved from the OS keychain (stored via fnox) into an environment variable, enabling subsequent commands to use it.

```bash
export OP_SERVICE_ACCOUNT_TOKEN=$(fnox get OP_SERVICE_ACCOUNT_TOKEN)
# Now can access 1Password secrets
fnox exec -- ./start.sh
```

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

### Getting GitHub App Credentials

Source: https://fnox.jdx.dev/leases/github-app.html

Instructions on how to obtain your GitHub App ID and Installation ID, and how to generate a private key.

```APIDOC
## Obtaining GitHub App Credentials

### Description
This section provides a step-by-step guide to retrieve the necessary credentials for your GitHub App, including the App ID, Installation ID, and generating a private key.

### Getting the App ID and Installation ID

1.  **App ID**: Navigate to your GitHub App's settings page (`Settings > Developer settings > GitHub Apps > Your App`). The App ID is displayed at the top of the page.
2.  **Installation ID**: After installing the app on an organization or account, find the Installation ID in the URL: `https://github.com/settings/installations/{installation_id}`. Alternatively, you can use the GitHub API:

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

### Generating a Private Key

1.  In your GitHub App settings, scroll down to the "Private keys" section.
2.  Click "Generate a new private key".
3.  Save the downloaded PEM file to a secure location on your system.
```

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

### GitHub Actions CI/CD Example for Deploying with Secrets

Source: https://fnox.jdx.dev/providers/aws-sm.html

Provides a GitHub Actions workflow example that configures AWS credentials and uses fnox to execute a deployment script with production secrets. This demonstrates integrating fnox into a CI/CD pipeline for secure deployments.

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

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

      - 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 secrets
        run: |
          fnox exec --profile production -- ./deploy.sh
```

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

### Install Bitwarden CLI

Source: https://fnox.jdx.dev/providers/bitwarden.html

Instructions for installing the Bitwarden CLI on different operating systems. It's often auto-installed with fnox via mise.

```bash
# macOS
brew install bitwarden-cli

# Linux
npm install -g @bitwarden/cli

# Windows
choco install bitwarden-cli
```

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

### Initialize password-store

Source: https://fnox.jdx.dev/providers/password-store.html

Initializes a new password-store, setting up the directory structure and associating it with a GPG key for encryption. This is a one-time setup step.

```bash
# Initialize with your GPG key ID
pass init <your-gpg-key-id>

# Example:
pass init 3AA5C34371567BD2

# Or with email:
pass init user@example.com
```

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

### Install 1Password CLI

Source: https://fnox.jdx.dev/providers/1password.html

Installs the 1Password CLI on macOS, Linux, and Windows. For Linux, it involves adding a GPG key and repository before installation.

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

# 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

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

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

### Install Infisical CLI

Source: https://fnox.jdx.dev/providers/infisical.html

Installs the Infisical CLI on macOS, Linux, or Windows. For Linux, it uses a script to set up the package manager. For Windows, it uses scoop. Alternatively, binaries can be downloaded directly.

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

# 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

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

# Or download from https://infisical.com/docs/cli/overview
```

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

### Initialize fnox Project

Source: https://fnox.jdx.dev/guide/quick-start.html

Initializes a new fnox project by creating a `fnox.toml` configuration file in the current directory. This is the first step to start managing secrets with fnox.

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

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

### Explicit File Imports Example (TOML)

Source: https://fnox.jdx.dev/guide/hierarchical-config.html

Illustrates how to explicitly import configuration files using the `import` key. This is useful for bundling shared secrets or environment-specific configurations.

```toml
# Explicit file imports
import = ["./shared/secrets.toml", "./envs/dev.toml"]
```

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

### Automate deployment with GitHub Actions

Source: https://fnox.jdx.dev/providers/1password.html

Example workflow for deploying applications using fnox and 1Password secrets in a CI/CD environment.

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

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

      - name: Setup fnox age key
        env:
          FNOX_AGE_KEY: ${{ secrets.FNOX_AGE_KEY }}
        run: echo "Age key configured"

      - name: Deploy with 1Password secrets
        run: |
          export OP_SERVICE_ACCOUNT_TOKEN=$(fnox get OP_SERVICE_ACCOUNT_TOKEN)
          fnox exec --profile production -- ./deploy.sh
```

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

### Install bws CLI

Source: https://fnox.jdx.dev/providers/bitwarden-sm.html

Instructions for installing the Bitwarden Secrets Manager CLI (`bws`). It mentions that `bws` is auto-installed via `mise` and 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
```

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

### Setup IAM Permissions and Enable API

Source: https://fnox.jdx.dev/leases/gcp-iam.html

Bash commands to grant the Service Account Token Creator role to a user and enable the IAM Credentials API for the project.

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

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

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

### Advanced fnox configuration options

Source: https://fnox.jdx.dev/guide/mise-integration.html

Examples of using specific profiles and custom binary paths within the mise environment configuration.

```toml
# Use production profile
_.fnox-env = { tools = true, profile = "production" }

# Custom fnox binary path
_.fnox-env = { fnox_bin = "/usr/local/bin/fnox" }
```

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

### Configure Bitwarden Provider in fnox.toml

Source: https://fnox.jdx.dev/providers/bitwarden.html

Example TOML configuration for setting up the Bitwarden provider in fnox, including optional parameters for collection and organization IDs.

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

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

### Onboard new team members to fnox

Source: https://fnox.jdx.dev/guide/real-world-example.html

Step-by-step commands for new developers to install fnox, generate age keys, and configure their environment for secret decryption.

```bash
git clone https://github.com/myorg/my-api
cd my-api
mise install
age-keygen -o ~/.config/fnox/age.txt
grep "public key:" ~/.config/fnox/age.txt
echo 'export FNOX_AGE_KEY=$(cat ~/.config/fnox/age.txt | grep "AGE-SECRET-KEY")' >> ~/.bashrc
source ~/.bashrc
echo 'eval "$(fnox activate bash)"' >> ~/.bashrc
npm run dev
```

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

### Install HashiCorp Vault CLI

Source: https://fnox.jdx.dev/providers/vault.html

Installs the HashiCorp Vault command-line interface on macOS using Homebrew and on Linux using apt package manager.

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

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

### Install YubiKey Provider

Source: https://fnox.jdx.dev/providers/yubikey.html

Command to add the YubiKey secure provider to fnox. This is the initial step for setting up YubiKey-based encryption.

```bash
fnox provider add secure yubikey
```

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

### Cloudflare Lease with Stored Credentials

Source: https://fnox.jdx.dev/leases/cloudflare.html

Integration example using 1Password to provide the parent API token, followed by executing a command with the generated lease.

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

[secrets]
CLOUDFLARE_API_TOKEN = { provider = "op", value = "Cloudflare/api token" }

[leases.cf]
type = "cloudflare"
account_id = "abc123def456"
duration = "1h"

[[leases.cf.policies]]
effect = "allow"
resources = { "com.cloudflare.api.account.abc123def456" = "*" }

[[leases.cf.policies.permission_groups]]
id = "c8fed203ed3043cba015a93ad1616f1f"
name = "Zone Read"

[[leases.cf.policies.permission_groups]]
id = "82e64a83756745bbbb1c9c2701bf816b"
name = "DNS Read"
```

```bash
fnox exec -- wrangler deploy
```

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

### Setup and Usage of Azure Key Vault with fnox

Source: https://fnox.jdx.dev/providers/azure-kms.html

This sequence demonstrates the end-to-end process of creating an Azure Key Vault key, configuring the fnox provider, and performing encryption and decryption operations.

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

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

### Root Configuration Example (TOML)

Source: https://fnox.jdx.dev/guide/hierarchical-config.html

Defines common secrets and providers at the project root. This configuration is inherited by all child services. It includes encryption providers and default secret values.

```toml
# project/fnox.toml

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

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

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

### Configure Multi-Environment Secrets

Source: https://fnox.jdx.dev/providers/aws-kms.html

Example configuration for managing secrets across different environments, using age for development and AWS KMS for production.

```toml
[providers]
age = { type = "age", recipients = ["age1..."] }
[secrets]
DATABASE_URL = { provider = "age", value = "encrypted-dev..." }
[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..." }
```

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

### Execute Commands with fnox and Secrets

Source: https://fnox.jdx.dev/providers/aws-ps.html

Shows how to use fnox to execute commands while automatically fetching and injecting secrets from AWS Parameter Store. Includes an example for running a script.

```bash
# Fetches all secrets from Parameter Store
fnox exec -- ./start-server.sh
```

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

### Multi-Environment Infisical Configuration with fnox

Source: https://fnox.jdx.dev/providers/infisical.html

An example of configuring fnox for multi-environment secret management using Infisical and the 'age' provider for bootstrapping. It shows how to define different environments and reference secrets from Infisical.

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

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

### Configuring Profile-Specific Providers (TOML)

Source: https://fnox.jdx.dev/guide/profiles.html

Demonstrates how to define different providers for specific profiles. The example shows default 'age' providers for development and AWS Secrets Manager providers for the 'production' profile.

```toml
# Default providers (for development)
[providers]
age = { type = "age", recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] }

# Production profile with AWS providers
[profiles.production]

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

[profiles.production.secrets]
DATABASE_URL = { provider = "aws", value = "database-url" }
```

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

### Setup and Usage of GCP KMS with FNOX

Source: https://fnox.jdx.dev/providers/gcp-kms.html

Commands to enable the Cloud KMS API, create necessary keys, configure the FNOX provider, and perform secret encryption and decryption operations.

```bash
gcloud services enable cloudkms.googleapis.com
gcloud kms keyrings create "fnox-keyring" --location="us-central1"
gcloud kms keys create "fnox-key" --keyring="fnox-keyring" --location="us-central1" --purpose="encryption"

cat >> fnox.toml << 'EOF'
[providers.gcpkms]
type = "gcp-kms"
project = "my-project-id"
location = "us-central1"
keyring = "fnox-keyring"
key = "fnox-key"
EOF

fnox set DATABASE_URL "postgresql://prod.example.com/db" --provider gcpkms
fnox get DATABASE_URL
```

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

### Organize Secrets Using Paths in Infisical

Source: https://fnox.jdx.dev/providers/infisical.html

Configure Infisical providers with specific paths to logically group secrets. This example shows how to define separate providers for API and database secrets, mapping them to their respective paths.

```toml
# Provider with specific path
[providers]
infisical-api = { type = "infisical", project_id = "abc123", environment = "dev", path = "/api" }
infisical-db = { type = "infisical", project_id = "abc123", environment = "dev", path = "/database" }

[secrets]
API_KEY = { provider = "infisical-api", value = "API_KEY" }  # → /api/API_KEY
DATABASE_URL = { provider = "infisical-db", value = "DATABASE_URL" }  # → /database/DATABASE_URL
```

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

### Execute GitHub CLI Command with App Token (Bash)

Source: https://fnox.jdx.dev/leases/github-app.html

This bash command demonstrates how to use fnox to execute a GitHub CLI command, utilizing a GitHub App installation token for authentication.

```bash
fnox exec -- gh pr list

```

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

### Use fnox to Get Secrets

Source: https://fnox.jdx.dev/providers/bitwarden.html

Example of how to retrieve secrets managed by Bitwarden using the fnox CLI after unlocking the vault or bootstrapping the session.

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

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

### Linux Secret Service Setup

Source: https://fnox.jdx.dev/providers/keychain.html

Provides installation commands for libsecret on different Linux distributions (Ubuntu/Debian, Fedora/RHEL, Arch Linux) to enable the Secret Service integration for fnox.

```bash
sudo apt-get install libsecret-1-0 libsecret-1-dev
```

```bash
sudo dnf install libsecret libsecret-devel
```

```bash
sudo pacman -S libsecret
```

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

### Initialize Fnox Project

Source: https://fnox.jdx.dev/guide/real-world-example.html

Commands to initialize a new Fnox project and a git repository.

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

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

### Quick Start: Set up KeePass Provider

Source: https://fnox.jdx.dev/providers/keepass.html

Demonstrates the initial steps to configure fnox to use a KeePass database. This includes setting the master password via an environment variable, configuring the provider in `fnox.toml`, and storing/retrieving a secret.

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

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

### Retrieve GitHub App Installations (Bash)

Source: https://fnox.jdx.dev/leases/github-app.html

This bash script uses curl to list GitHub App installations. It requires a JWT for authentication and targets the GitHub API to fetch installation details.

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

```

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

### Install Age CLI

Source: https://fnox.jdx.dev/providers/age.html

Commands to install the Age encryption tool on macOS and Linux systems.

```bash
# macOS
brew install age

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

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

### Setup Local Vaultwarden Server for Testing

Source: https://fnox.jdx.dev/providers/bitwarden.html

This bash script, sourced from './test/setup-bitwarden-test.sh', is used to set up a local Vaultwarden server for testing purposes. It includes instructions for creating an account, logging in, and unlocking the vault, along with commands to run tests using 'mise' and 'bats'.

```bash
# Start local vaultwarden server
source ./test/setup-bitwarden-test.sh

# Follow on-screen instructions:
# 1. Create account at https://localhost:8080 (accept self-signed certificate)
# 2. Login: export NODE_TLS_REJECT_UNAUTHORIZED=0 && bw login
# 3. Unlock: export BW_SESSION=$(bw unlock --raw)

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

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

### Install libsecret on Linux

Source: https://fnox.jdx.dev/providers/keychain.html

Installs the necessary libsecret library and development files on Debian/Ubuntu-based systems for Linux Secret Service integration.

```bash
sudo apt-get install libsecret-1-0 libsecret-1-dev
```

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

### Install and Open KeePassXC

Source: https://fnox.jdx.dev/providers/keepass.html

Provides commands to install the KeePassXC GUI tool on macOS and open a specific database file for management.

```bash
brew install --cask keepassxc
keepassxc ~/secrets.kdbx
```

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

### Install password-store (pass)

Source: https://fnox.jdx.dev/providers/password-store.html

Installs the password-store utility using package managers for different operating systems. This is a prerequisite for using pass with fnox.

```bash
# macOS
brew install pass

# Linux
sudo apt install pass
```

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

# Arch Linux
sudo pacman -S pass
```

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

### Common Fnox Profile Patterns: Per-Developer Profiles (TOML & Bash)

Source: https://fnox.jdx.dev/guide/profiles.html

Illustrates how to set up individual profiles for developers (e.g., 'alice', 'bob') with their own local database configurations. Includes a bash example showing how to activate a developer profile using `export FNOX_PROFILE`.

```toml
[profiles.alice]

[profiles.alice.secrets]
DATABASE_URL = { default = "postgresql://localhost/alice_db" }

[profiles.bob]

[profiles.bob.secrets]
DATABASE_URL = { default = "postgresql://localhost/bob_db" }
```

```bash
export FNOX_PROFILE=alice
fnox exec -- npm start
```

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

### Team Onboarding Workflow with fnox

Source: https://fnox.jdx.dev/guide/import-export.html

Outlines a process for onboarding new team members by exporting example secrets, allowing them to fill in real values, and then importing them securely with encryption. This standardizes secret management for teams. Requires fnox CLI.

```bash
# 1. Export example secrets (with dummy values)
fnox export --format json > secrets.example.json

# 2. Team member fills in real values
cp secrets.example.json secrets.json
# Edit secrets.json with real credentials

# 3. Import with encryption
fnox import -i secrets.json json --provider age

# 4. Delete plaintext file
rm secrets.json
```

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

### fnox Configuration Example (TOML)

Source: https://fnox.jdx.dev/guide/sync.html

Illustrates how to configure remote providers (like 1Password) and local encryption providers (like age) within `fnox.toml`. It also shows the structure of secrets, including how synced secrets are represented with a `sync` field in `fnox.local.toml`.

```toml
# fnox.toml (committed) 
[providers.op]
type = "1password"
vault = "Engineering"

[secrets]
DATABASE_URL = { provider = "op", value = "Database/url" }
STRIPE_KEY = { provider = "op", value = "Stripe/secret-key" }
SENDGRID_KEY = { provider = "op", value = "SendGrid/api-key" }
```

```toml
# fnox.toml (committed — the source of truth):
[providers.op]
type = "1password"
vault = "Engineering"

[providers.age]
type = "age"
recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]

[secrets]
DATABASE_URL = { provider = "op", value = "Database/url" }
STRIPE_KEY = { provider = "op", value = "Stripe/secret-key" }
SENDGRID_KEY = { provider = "op", value = "SendGrid/api-key" }
```

```toml
# fnox.local.toml (gitignored — your local cache):
[secrets]
DATABASE_URL = { provider = "op", value = "Database/url", sync = { provider = "age", value = "YWdlLWVuY3J5cHRpb24..." } }
STRIPE_KEY = { provider = "op", value = "Stripe/secret-key", sync = { provider = "age", value = "YWdlLWVuY3J5cHRpb24..." } }
SENDGRID_KEY = { provider = "op", value = "SendGrid/api-key", sync = { provider = "age", value = "YWdlLWVuY3J5cHRpb24..." } }
```

```toml
# Using a YubiKey with age-plugin-yubikey:
[providers.age]
type = "age"
recipients = ["age1yubikey1q..."]  # YubiKey recipient
```

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

### Install BWS CLI via Homebrew

Source: https://fnox.jdx.dev/providers/bitwarden-sm.html

This command installs the Bitwarden Secrets Manager CLI using the Homebrew package manager. Use this if the 'bws' command is not found in your system path.

```bash
brew install bws
```

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

### Configure GitHub App Lease Backend (TOML)

Source: https://fnox.jdx.dev/leases/github-app.html

This TOML configuration sets up the github-app lease backend. It requires the app ID, installation ID, and optionally a private key file path. Permissions and repositories can be scoped.

```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
[providers.op]
type = "1password"
vault = "Infrastructure"

[secrets]
FNOX_GITHUB_APP_PRIVATE_KEY = { provider = "op", value = "GitHub App/private key" }

[leases.github]
type = "github-app"
app_id = "12345"
installation_id = "67890"

```

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

```

```toml
[leases.github]
type = "github-app"
app_id = "12345"
installation_id = "67890"
private_key_file = "~/.config/fnox/github-app.pem"
api_base = "https://github.example.com/api/v3"

```

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

```

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

### Manage Global Configuration via CLI

Source: https://fnox.jdx.dev/reference/configuration.html

Commands to initialize the global configuration file, 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
```

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

### Daily Workflow with Prompt-Based Credentials

Source: https://fnox.jdx.dev/guide/leases.html

This bash command sequence demonstrates the daily workflow for prompt-based credentials. It shows how to create a lease interactively using 'fnox lease create aws -i', where you manually paste credentials. Subsequent 'fnox exec' commands then utilize the cached, short-lived credentials without further prompting.

```bash
$ fnox lease create aws -i
AWS_ACCESS_KEY_ID (AWS access key): AKIA...
AWS_SECRET_ACCESS_KEY (AWS secret key): wJalr...
AWS_SESSION_TOKEN (AWS session token (optional)): 

Lease created (expires in 1h0m)

AWS_ACCESS_KEY_ID         ASIA...F3YQ
AWS_SECRET_ACCESS_KEY     wJal...EKEY
AWS_SESSION_TOKEN         FwoG...==
Expires                   2024-01-15T10:00:00+00:00
```

```bash
# Uses the cached lease (no prompting, no stored master creds)
fnox exec -- aws s3 ls
fnox exec -- terraform plan
```

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

### Migration Workflows

Source: https://fnox.jdx.dev/guide/import-export.html

Guides for migrating secrets between different formats and providers.

```APIDOC
## From .env to fnox with Encryption

### Description
Migrate secrets from a `.env` file to fnox, encrypting them using the `age` provider.

### Method
CLI Command

### Endpoint
N/A

### Steps
1. Configure the `age` provider in `fnox.toml`.
2. Import secrets from `.env` using the `age` provider.
3. Remove the original `.env` file.

### Request Example
```bash
# 1. Set up age provider (example)
cat >> fnox.toml << 'EOF'
[providers.age]
type = "age"
recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]
EOF

# 2. Import and encrypt all secrets
fnox import -i .env --provider age

# 3. Remove .env file
rm .env
```

## From fnox to .env (for legacy tools)

### Description
Export secrets from fnox into a `.env` file format for use with legacy tools.

### Method
CLI Command

### Endpoint
N/A

### Request Example
```bash
fnox exec env | grep -v '^_' > .env
# Or using the export command:
fnox export > .env
```

## Between Providers

### Description
Migrate secrets from one provider to another (e.g., AWS Secrets Manager to `age`).

### Method
CLI Command

### Endpoint
N/A

### Steps
1. Export secrets from the source provider.
2. Configure the target provider in `fnox.toml`.
3. Re-import secrets using the target provider.
4. Verify the migration.

### Request Example
```bash
# 1. Export from AWS Secrets Manager
fnox export --profile production --format json > prod-secrets.json

# 2. Switch to age provider (example configuration)
cat >> fnox.toml << 'EOF'
[providers.age]
type = "age"
recipients = ["age1..."]
EOF

# 3. Re-import with new provider
fnox import -i prod-secrets.json json --provider age

# 4. Verify
fnox list
```

## Team Onboarding

### Description
Facilitate team onboarding by providing example secrets and a secure import process.

### Method
CLI Command

### Endpoint
N/A

### Steps
1. Export example secrets in JSON format.
2. Team members fill in real values in a local copy.
3. Import the filled secrets using an encryption provider.
4. Delete the plaintext file.

### Request Example
```bash
# 1. Export example secrets
fnox export --format json > secrets.example.json

# 2. Team member fills in real values
cp secrets.example.json secrets.json
# Edit secrets.json with real credentials

# 3. Import with encryption
fnox import -i secrets.json json --provider age

# 4. Delete plaintext file
rm secrets.json
```
```

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

### Bootstrap Secret Retrieval

Source: https://fnox.jdx.dev/providers/password-store.html

Example of using stored provider tokens to bootstrap environment variables for deployment scripts.

```bash
export AWS_ACCESS_KEY_ID=$(fnox get AWS_ACCESS_KEY_ID)
export AWS_SECRET_ACCESS_KEY=$(fnox get AWS_SECRET_ACCESS_KEY)
fnox exec -- ./deploy.sh
```

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

### Initializing Global Configuration (Bash)

Source: https://fnox.jdx.dev/guide/hierarchical-config.html

Commands to initialize the global fnox configuration, set global secrets like API tokens, and add encryption providers.

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

# Add secrets to global config
fnox set GITHUB_TOKEN "ghp_..." --global
fnox set NPM_TOKEN "npm_..." --global

# Add providers to global config
fnox provider add age age --global
```

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

### Create Secrets via AWS CLI

Source: https://fnox.jdx.dev/providers/aws-sm.html

Examples of creating plaintext and JSON-formatted secrets using the AWS CLI.

```bash
aws secretsmanager create-secret \
  --name "myapp/database-url" \
  --secret-string "postgresql://prod.db.example.com/mydb"

aws secretsmanager create-secret \
  --name "myapp/db-creds" \
  --secret-string '{"username":"admin","password":"secret123"}'
```

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

### Configure Custom Environment Variable

Source: https://fnox.jdx.dev/leases/azure-token.html

Example of overriding the default environment variable name for the Azure access token.

```toml
[leases.azure]
type = "azure-token"
scope = "https://graph.microsoft.com/.default"
env_var = "GRAPH_TOKEN"
```

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

### CI/CD: Staging Deployment with Warnings (YAML)

Source: https://fnox.jdx.dev/guide/missing-secrets.html

This GitHub Actions YAML example configures `fnox` for staging deployments to issue warnings rather than fail when secrets are missing. Setting `FNOX_IF_MISSING: warn` allows the deployment to proceed while alerting the team to potential configuration gaps.

```yaml
# .github/workflows/staging.yml
jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to staging
        env:
          FNOX_IF_MISSING: warn # Print warnings but continue
        run: |
          fnox exec --profile staging -- ./deploy.sh
```

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

### Get a Secret with fnox

Source: https://fnox.jdx.dev/guide/quick-start.html

Retrieves the value of a previously set secret. This command outputs the secret's value to the console.

```bash
fnox get DATABASE_URL
```

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

### Import Secrets from .env Files using fnox

Source: https://fnox.jdx.dev/guide/import-export.html

Demonstrates how to import secrets from a .env file into fnox. It shows basic import and how to specify a provider for encryption during import. Dependencies include the fnox CLI and a .env file.

```bash
# Import from .env file
fnox import -i .env

# Import and specify provider
fnox import -i .env --provider age
```

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

### Configure Secret Providers

Source: https://fnox.jdx.dev/reference/configuration.html

Examples of how to define various secret providers such as Bitwarden, HashiCorp Vault, and OS Keychain in the TOML configuration.

```toml
[providers]
bitwarden = { type = "bitwarden", collection = "collection-id", organization_id = "org-id" }
vault = { type = "vault", address = "https://vault.example.com:8200", path = "secret/myapp", token = "hvs.CAESIJ..." }
keychain = { type = "keychain", service = "fnox", prefix = "myapp/" }
```

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

### Using Fnox Profiles via Command Line (Bash)

Source: https://fnox.jdx.dev/guide/profiles.html

Illustrates how to interact with Fnox profiles using command-line arguments. Shows commands to get secrets using the default profile, a specific profile ('staging'), and executing scripts with a specified profile ('production').

```bash
# Use default profile
fnox get API_URL

# Use specific profile
fnox get API_URL --profile staging
fnox exec --profile production -- ./deploy.sh
```

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

### Git Integration with password-store

Source: https://fnox.jdx.dev/providers/password-store.html

Demonstrates how to use Git with your password-store for version control. This allows you to track changes to your secrets and collaborate with others.

```bash
# Initialize git repo in password-store
pass git init

# Add remote
pass git remote add origin https://github.com/username/password-store.git

# Configure git
pass git config user.name "Your Name"
pass git config user.email "you@example.com"

# Changes are automatically committed when using fnox set
fnox set API_KEY "new-key" --provider pass

# Push changes
pass git push
```
Tokens:
Raw