CLI Reference
Every qring command in one place. Just getting set up? Start with Getting Started or wire up your editor in MCP Setup.
Reference
CLI complete reference
Every CLI command and option is listed below with at least one real invocation example. 55 commands in total.
qring set <key> [value]
Store a secret (with optional quantum metadata)
Options
Examples
$ qring set OPENAI_API_KEY "sk-..." --project --env dev --tags ai,backend
$ qring set DB_PASSWORD --ttl 3600 --rotation-format password --requires-approval
qring get <key>
Retrieve a secret (collapses superposition if needed)
Options
Examples
$ qring get OPENAI_API_KEY --project --env prod
qring delete <key> (alias: rm)
Remove a secret from the keyring
Options
Examples
$ qring delete LEGACY_TOKEN --project
qring has <key>
Check whether a secret exists — exit 0 if present, 1 if not; decay-aware (expired counts as absent)
Options
Examples
$ qring has OPENAI_API_KEY --quiet && echo configured
qring list (alias: ls)
List all secrets with quantum status indicators
Options
Examples
$ qring list --project --tag payments --filter "STRIPE_*" --show-decay
qring inspect <key>
Show full quantum state of a secret
Options
Examples
$ qring inspect OPENAI_API_KEY --project
qring export
Export secrets as .env or JSON (collapses superposition)
Options
Examples
$ qring export --format env --project --env prod --keys OPENAI_API_KEY,STRIPE_KEY
qring import <file>
Import secrets from a .env file
Options
Examples
$ qring import .env --project --skip-existing
qring check
Validate project secrets against .q-ring.json manifest
Options
Examples
$ qring check --project-path .
qring validate [key]
Test if a secret is actually valid with its target service
Options
Examples
$ qring validate OPENAI_API_KEY --project
$ qring validate --all --manifest --project
qring exec <command...>
Run a command with secrets injected into its environment (output auto-redacted)
Options
Examples
$ qring exec --project --profile restricted --keys OPENAI_API_KEY -- node "scripts/smoke.js"
qring run <command...>
Run a command with only declared secrets injected — .q-ring.json manifest keys plus qring:// refs from .env (least-privilege sibling of exec; output auto-redacted)
Options
Examples
$ qring run -- pnpm dev
$ qring run --dry-run -- pnpm dev
$ qring run --env prod --env-file .env.prod -- ./deploy.sh
qring setup <editor>
Wire the q-ring MCP server into an editor's MCP config (cursor, kiro, claude) — merged non-destructively
Options
Examples
$ qring setup cursor
$ qring setup kiro --dry-run
qring push <target>
Push manifest secrets to a deployment platform via its own CLI (github, vercel, cloudflare) — values travel over stdin, never argv; every push is audited
Options
Examples
$ qring push github --repo you/your-app
$ qring push vercel --vercel-env production,preview
$ qring push github --keys DATABASE_URL,API_KEY --dry-run
qring scan [dir]
Scan a codebase for hardcoded secrets
Options
Examples
$ qring scan src --fix --project
qring lint <files...>
Lint specific files for hardcoded secrets (with optional auto-fix)
Options
Examples
$ qring lint src/config.ts src/client.ts --fix --project
qring context (alias: describe)
Show safe, redacted project context for AI agents (no secret values exposed)
Options
Examples
$ qring context --project --json
qring remember <key> <value>
Store a key-value pair in encrypted agent memory (persists across sessions)
No command-specific options.
Examples
$ qring remember deployment_note "rotate Stripe key after release"
qring recall [key]
Retrieve a value from agent memory, or list all keys
Options
Examples
$ qring recall deployment_note
$ qring recall
qring forget <key>
Delete a key from agent memory
Options
Examples
$ qring forget deployment_note
qring approve <key>
Grant a scoped, reasoned, HMAC-verified approval token for MCP secret access
Options
Examples
$ qring approve OPENAI_API_KEY --project --for 1800 --reason "temporary agent read"
qring approvals
List all approval tokens with verification status
Options
Examples
$ qring approvals
qring hook:install
Install a git pre-commit hook that scans for hardcoded secrets
Options
Examples
$ qring hook:install --project-path .
qring hook:uninstall
Remove the q-ring pre-commit hook
Options
Examples
$ qring hook:uninstall --project-path .
qring hook:run
Run the pre-commit secret scan (called by the git hook)
No command-specific options.
Examples
$ qring hook:run
qring wizard <name>
Set up a new service integration with secrets, manifest, and hooks
Options
Examples
$ qring wizard stripe --keys STRIPE_KEY,STRIPE_WEBHOOK_SECRET --provider stripe --tags payments,prod
qring analyze
Analyze secret usage patterns and provide optimization suggestions
Options
Examples
$ qring analyze --project
qring env
Show detected environment (wavefunction collapse context)
Options
Examples
$ qring env --project-path .
qring generate (alias: gen)
Generate a cryptographic secret (quantum noise)
Options
Examples
$ qring generate --format api-key --prefix sk- --save OPENAI_API_KEY --project
qring entangle <sourceKey> <targetKey>
Link two secrets — rotating one updates the other
Options
Examples
$ qring entangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker
qring disentangle <sourceKey> <targetKey>
Unlink two entangled secrets
Options
Examples
$ qring disentangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker
qring tunnel create <value>
Create a tunneled secret (returns tunnel ID)
Options
Examples
$ qring tunnel create "temp-token" --ttl 300 --max-reads 1
qring tunnel read <id>
Read a tunneled secret (may self-destruct)
No command-specific options.
Examples
$ qring tunnel read tu_abc123
qring tunnel destroy <id>
Destroy a tunneled secret immediately
No command-specific options.
Examples
$ qring tunnel destroy tu_abc123
qring tunnel list (alias: tunnel ls)
List active tunnels
Options
Examples
$ qring tunnel list
qring teleport pack
Pack secrets into an encrypted bundle
Options
Examples
$ qring teleport pack --project --keys OPENAI_API_KEY,STRIPE_KEY > bundle.qring
qring teleport unpack [bundle]
Unpack and import secrets from an encrypted bundle
Options
Examples
$ qring teleport unpack "$(cat bundle.qring)" --project --dry-run
qring audit
View the audit log (observer effect)
Options
Examples
$ qring audit --key OPENAI_API_KEY --action read --limit 50
qring audit:verify
Verify the integrity of the audit hash chain
Options
Examples
$ qring audit:verify
qring audit:export
Export audit events in a portable format
Options
Examples
$ qring audit:export --since 2026-03-01 --format json -o audit.json
qring health
Check the health of all secrets
Options
Examples
$ qring health --project
qring hook add
Register a new hook
Options
Examples
$ qring hook add --key DB_PASSWORD --action write,rotate --exec "pnpm restart:api"
$ qring hook add --tag payments --url https://hooks.example.com/qring --action rotate
qring hook list (alias: hook ls)
List all registered hooks
Options
Examples
$ qring hook list
qring hook remove <id> (alias: hook rm)
Remove a hook by ID
No command-specific options.
Examples
$ qring hook remove hk_abc123
qring hook enable <id>
Enable a hook
No command-specific options.
Examples
$ qring hook enable hk_abc123
qring hook disable <id>
Disable a hook
No command-specific options.
Examples
$ qring hook disable hk_abc123
qring hook test <id>
Dry-run a hook with a mock payload
No command-specific options.
Examples
$ qring hook test hk_abc123
qring env:generate
Generate a .env file from the project manifest (.q-ring.json)
Options
Examples
$ qring env:generate --project-path . --env prod -o .env
qring status
Launch the live status dashboard in your browser — KPIs, secrets table, manifest, policy, approvals, hooks, anomalies, and audit feed (SSE, never shows secret values)
Options
Examples
$ qring status --port 9876 --no-open
qring agent
Start the autonomous agent (background monitor)
Options
Examples
$ qring agent --once --auto-rotate --project-path .,../worker
qring rotate <key>
Attempt issuer-native rotation of a secret via its provider
Options
Examples
$ qring rotate OPENAI_API_KEY --project --provider openai
qring ci:validate
CI-oriented batch validation of all secrets (exit code 1 on failure)
Options
Examples
$ qring ci:validate --project --json
qring policy
Show project governance policy summary
Options
Examples
$ qring policy --json
qring doctor
Diagnose the q-ring installation — keyring backend round-trip, audit dir + hash chain, .q-ring.json validity, policy, qring-mcp on PATH
Options
Examples
$ qring doctor
$ qring doctor --json
qring completion <shell>
Print a shell completion script generated from the live command tree (bash, zsh, fish)
No command-specific options.
Examples
$ qring completion zsh > ~/.zsh/completions/_qring