secret/README.md

@oc-forge/secret

🔐 Infisical secret manager CLI with local caching.

Manage secrets from Infisical with a simple CLI. Caches secrets locally (24h TTL) to minimize API calls.

Install

# Requires Bun runtime
npm install -g @oc-forge/secret

Setup

Create a config file at ~/.config/oc-secret/config.json:

{
  "clientId": "<your-infisical-client-id>",
  "clientSecret": "<your-infisical-client-secret>",
  "projectId": "<your-infisical-project-id>",
  "env": "dev"
}

Or use environment variables:

export INFISICAL_CLIENT_ID=xxx
export INFISICAL_CLIENT_SECRET=xxx
export INFISICAL_PROJECT_ID=xxx
export INFISICAL_ENV=dev  # optional, defaults to "dev"

Usage

# Get a secret (cache-first)
secret get MY_API_KEY

# Get a secret (skip cache)
secret get MY_API_KEY --fresh

# Set/update a secret
secret set MY_API_KEY "new-value"

# List all secret keys
secret list

# List with values
secret list --show

# Sync all secrets to local cache
secret sync

# Run a command with all secrets as env vars
secret exec -- node server.js

How it works

1. Cache-first: secret get checks local cache (~/.config/oc-secret/cache.json) before hitting the API
2. 24h TTL: Cache entries expire after 24 hours (configurable via ttlMs in config)
3. Upsert: secret set creates or updates the secret on Infisical and updates local cache
4. Exec: secret exec injects all secrets as environment variables into a child process

Output

• Secret values go to stdout (clean, no decoration)
• Status messages go to stderr (won't pollute $(secret get KEY))

# Safe to use in shell substitution
TOKEN=$(secret get MY_TOKEN)

Security

• Cache file is chmod 600 (owner-only read/write)
• Credentials never leave your machine
• Universal Auth (machine identity) — no user login required

License

MIT — 小橘爪作 🐾