Skip to content
Documentation

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. 68 commands in total.

68 of 68

qring set <key> [value]

Store a secret (with optional quantum metadata)

Options

-g, --global-p, --project--team <id>--org <id>--project-path <path>-e, --env <env>--ttl <seconds>--expires <iso>--description <desc>--tags <tags> (replaces existing tags; omit to keep them)--clear-tags (remove existing tags; refused together with --tags)--rotation-format <format>--rotation-prefix <prefix>--requires-approval--jit-provider <provider>--rotate-every <days> (rotation reminder, 1-3650)

Examples

qring set
$ qring set OPENAI_API_KEY "sk-..." --project --env dev --tags ai,backend
qring set
$ qring set DB_PASSWORD --ttl 3600 --rotation-format password --requires-approval
qring set
$ qring set LEGACY_TOKEN --clear-tags

qring get <key>

Retrieve a secret (collapses superposition if needed)

Options

-g, --global-p, --project--team <id>--org <id>--project-path <path>-e, --env <env>--raw

Examples

qring get
$ qring get OPENAI_API_KEY --project --env prod

qring delete <key> (alias: rm)

Remove a secret from the keyring

Options

-g, --global-p, --project--project-path <path>-y, --yes--json

Examples

qring delete
$ 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

-g, --global-p, --project--team <id>--org <id>--project-path <path>-q, --quiet--json

Examples

qring has
$ qring has OPENAI_API_KEY --quiet && echo configured

qring list (alias: ls)

List all secrets with quantum status indicators

Options

-g, --global-p, --project--team <id>--org <id>--project-path <path>--show-decay-t, --tag <tag>--expired--stale-f, --filter <pattern>--json

Examples

qring list
$ qring list --project --tag payments --filter "STRIPE_*" --show-decay

qring inspect <key>

Show full quantum state of a secret

Options

-g, --global-p, --project--project-path <path>--json

Examples

qring inspect
$ qring inspect OPENAI_API_KEY --project

qring export

Export secrets as .env or JSON (collapses superposition)

Options

-f, --format <format>-g, --global-p, --project--project-path <path>-e, --env <env>-k, --keys <keys>-t, --tags <tags>

Examples

qring export
$ qring export --format env --project --env prod --keys OPENAI_API_KEY,STRIPE_KEY

qring import <file>

Import secrets from a .env file

Options

-g, --global-p, --project--project-path <path>-e, --env <env>--skip-existing--dry-run--json

Examples

qring import
$ qring import .env --project --skip-existing

qring check

Validate project secrets against .q-ring.json manifest

Options

--project-path <path>--json

Examples

qring check
$ qring check --project-path .

qring validate [key]

Test if a secret is actually valid with its target service

Options

-g, --global-p, --project--project-path <path>--provider <name>--all--manifest--list-providers--json

Examples

qring validate
$ qring validate OPENAI_API_KEY --project
qring validate
$ qring validate --all --manifest --project

qring exec <command...>

Run a command with secrets injected into its environment (output auto-redacted: each value verbatim, in its base64 / hex / URL / JSON-escaped forms, and as any 16+ character slice of its credential part, replaced with [QRING:REDACTED:<KEY>]; refuses to spawn if redaction cannot be set up)

Options

-g, --global-p, --project--project-path <path>-e, --env <env>-k, --keys <keys>-t, --tags <tags>--profile <name> (unknown names are refused)

Examples

qring exec
$ qring exec --project --profile restricted --keys OPENAI_API_KEY -- npm test

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

--project-path <path>-e, --env <env>--env-file <files...>--no-manifest--profile <name> (unknown names are refused)--strict--dry-run

Examples

qring run
$ qring run -- pnpm dev
qring run
$ qring run --dry-run -- pnpm dev
qring run
$ 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

-g, --global--project-path <path>--force--dry-run--json

Examples

qring setup
$ qring setup cursor
qring setup
$ qring setup kiro --dry-run

qring push <target>

Push manifest secrets to a deployment platform via its own CLI (github, vercel, cloudflare, fly, railway, netlify) - values travel over stdin (or a 0600 temp file for Netlify), never argv; every push is audited

Options

-k, --keys <keys>--project-path <path>-e, --env <env>--repo <owner/name>--vercel-env <envs>--app <name> (fly)--service <name> / --railway-env <name> (railway)--site <id> (netlify)--dry-run--json

Examples

qring push
$ qring push github --repo you/your-app
qring push
$ qring push vercel --vercel-env production,preview
qring push
$ qring push fly --app my-app
qring push
$ qring push railway --service api --railway-env production
qring push
$ qring push netlify --site 1234-abcd
qring push
$ qring push github --keys DATABASE_URL,API_KEY --dry-run

qring scan [dir]

Scan a codebase for hardcoded secrets

Options

--fix-g, --global-p, --project--project-path <path>--json

Examples

qring scan
$ qring scan src --fix --project

qring lint <files...>

Lint specific files for hardcoded secrets (with optional auto-fix)

Options

--fix-g, --global-p, --project--project-path <path>--json

Examples

qring lint
$ 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; the bare --json shape is deprecated and moves to the { ok, data } wrapper in 1.0)

Options

-g, --global-p, --project--project-path <path>--json

Examples

qring context
$ 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
$ qring remember deployment_note "rotate Stripe key after release"

qring recall [key]

Retrieve a value from agent memory, or list all keys

Options

--json

Examples

qring recall
$ qring recall deployment_note
qring recall
$ qring recall

qring forget <key>

Delete a key from agent memory

Options

--all-y, --yes

Examples

qring forget
$ qring forget deployment_note

qring approve <key>

Grant a scoped, reasoned, HMAC-verified approval token for MCP secret access

Options

-g, --global-p, --project--project-path <path>--for <seconds>--reason <text>--revoke--list (deprecated, removed in 1.0: use qring approvals)

Examples

qring approve
$ qring approve OPENAI_API_KEY --project --for 1800 --reason "temporary agent read"

qring approvals

List all approval tokens with verification status

Options

--json

Examples

qring approvals
$ qring approvals

qring hook:install

Install a git pre-commit hook that scans for hardcoded secrets

Options

--project-path <path>

Examples

qring hook:install
$ qring hook:install --project-path .

qring hook:uninstall

Remove the q-ring pre-commit hook

Options

--project-path <path>

Examples

qring hook:uninstall
$ 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 hook:run

qring wizard <name>

Set up a new service integration with secrets, manifest, and hooks

Options

--keys <keys>--provider <provider>--tags <tags>--hook-exec <cmd>-g, --global-p, --project--project-path <path>-y, --yes

Examples

qring wizard
$ 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

-g, --global-p, --project--project-path <path>--json

Examples

qring analyze
$ qring analyze --project

qring env

Show detected environment (wavefunction collapse context)

Options

--project-path <path>--json

Examples

qring env
$ qring env --project-path .

qring generate (alias: gen)

Generate a cryptographic secret (quantum noise)

Options

-f, --format <format>-l, --length <n>--prefix <prefix>-s, --save <key>-g, --global-p, --project--project-path <path>

Examples

qring generate
$ 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

-g, --global--source-project <path>--target-project <path>

Examples

qring entangle
$ qring entangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker

qring disentangle <sourceKey> <targetKey>

Unlink two entangled secrets

Options

-g, --global--source-project <path>--target-project <path>

Examples

qring disentangle
$ qring disentangle API_KEY API_KEY_BACKUP --source-project . --target-project ../worker

qring tunnel create <value>

Create a tunneled secret (returns tunnel ID)

Options

--ttl <seconds>--max-reads <n>

Examples

qring tunnel
$ 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
$ qring tunnel read tun_abc123

qring tunnel destroy <id>

Destroy a tunneled secret immediately

No command-specific options.

Examples

qring tunnel
$ qring tunnel destroy tun_abc123

qring tunnel list (alias: tunnel ls)

List active tunnels

Options

--json

Examples

qring tunnel
$ qring tunnel list

qring teleport pack

Pack secrets into an encrypted bundle - prompts for a passphrase, or with --to encrypts to teammates' recipient keys (no passphrase)

Options

-k, --keys <keys>--to <recipient...> (repeatable or comma-separated qring1… strings)-g, --global-p, --project--project-path <path>

Examples

qring teleport
$ qring teleport pack --project --keys OPENAI_API_KEY,STRIPE_KEY > bundle.qring
qring teleport
$ qring teleport pack --keys API_KEY --to qring1a3F… --to qring1Zz9… > bundle.qring

qring teleport unpack [bundle]

Unpack and import secrets from an encrypted bundle - passphrase bundles prompt; recipient bundles use the identity in your keyring

Options

-g, --global-p, --project--project-path <path>--dry-run (shows the addressed recipient ids and whether you are one)-y, --yes

Examples

qring teleport
$ qring teleport unpack "$(cat bundle.qring)" --project --dry-run

qring teleport keygen

Create your teleport identity: an X25519 keypair whose private half is stored in the OS keyring; prints the qring1… recipient string to share

Options

--force (replace an existing identity)

Examples

qring teleport
$ qring teleport keygen
qring teleport
$ qring teleport keygen >> team-recipients.txt

qring teleport identity

Print your recipient string again (exit 1 with a keygen hint if you have none)

No command-specific options.

Examples

qring teleport
$ qring teleport identity

qring promote <key>

Copy a secret's value from one environment state to another; no-op when the target already matches, asks (or needs --force) before overwriting a different value

Options

--from <env>--to <env>-g, --global-p, --project--team <id>--org <id>--project-path <path>-f, --force / -y, --yes--json

Examples

qring promote
$ qring promote DATABASE_URL --from staging --to prod
qring promote
$ qring promote DATABASE_URL --from staging --to prod --force --json

qring diff <envA> <envB>

Compare two environments key by key - same / different / missing on one side / single-value; statuses only, never values; exits 1 on drift

Options

-k, --keys <keys>-g, --global-p, --project--team <id>--org <id>--project-path <path>--json

Examples

qring diff
$ qring diff staging prod
qring diff
$ qring diff dev staging --keys API_KEY,DATABASE_URL --json

qring rotate:due

List secrets whose rotation reminder is due soon or overdue, most overdue first (--all lists every scheduled secret)

Options

--all-g, --global-p, --project--team <id>--org <id>--project-path <path>--json

Examples

qring rotate:due
$ qring rotate:due
qring rotate:due
$ qring rotate:due --all --json

qring audit

View the audit log (observer effect)

Options

-k, --key <key>-a, --action <action>-n, --limit <n>--anomalies--json

Examples

qring audit
$ qring audit --key OPENAI_API_KEY --action read --limit 50

qring audit:verify

Verify the integrity of the audit hash chain

Options

--json

Examples

qring audit:verify
$ qring audit:verify

qring audit:export

Export audit events in a portable format

Options

--since <date>--until <date>--format <fmt>-o, --output <file>

Examples

qring audit:export
$ qring audit:export --since 2026-03-01 --format json -o audit.json

qring health

Check the health of all secrets

Options

-g, --global-p, --project--project-path <path>--json

Examples

qring health
$ qring health --project

qring hook add

Register a new hook

Options

--key <key>--key-pattern <pattern>--tag <tag>--scope <scope>--action <actions>--exec <command>--url <url>--signal-target <target>--signal-name <signal>--description <desc>

Examples

qring hook
$ qring hook add --key DB_PASSWORD --action write,rotate --exec "pnpm restart:api"
qring hook
$ qring hook add --tag payments --url https://hooks.example.com/qring --action rotate

qring hook list (alias: hook ls)

List all registered hooks

Options

--json

Examples

qring hook
$ qring hook list

qring hook remove <id> (alias: hook rm)

Remove a hook by ID

No command-specific options.

Examples

qring hook
$ qring hook remove hk_abc123

qring hook enable <id>

Enable a hook - shell and signal hooks registered over MCP start disabled and run only after you enable them here

No command-specific options.

Examples

qring hook
$ qring hook enable hk_abc123

qring hook disable <id>

Disable a hook

No command-specific options.

Examples

qring hook
$ qring hook disable hk_abc123

qring hook test <id>

Dry-run a hook with a mock payload

No command-specific options.

Examples

qring hook
$ qring hook test hk_abc123

qring env:generate

Generate a .env file from the project manifest (.q-ring.json)

Options

--project-path <path>-o, --output <file>-e, --env <env>-y, --yes

Examples

qring env:generate
$ 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

--port <port>--no-open

Examples

qring status
$ qring status --port 9876 --no-open

qring agent

Start the autonomous agent (background monitor)

Options

-i, --interval <seconds>--auto-rotate-v, --verbose--project-path <paths>--once

Examples

qring agent
$ qring agent --once --auto-rotate --project-path .,../worker

qring rotate <key>

Attempt issuer-native rotation of a secret via its provider

Options

-g, --global-p, --project--project-path <path>--provider <name>--json

Examples

qring rotate
$ qring rotate OPENAI_API_KEY --project --provider openai

qring ci:validate

CI-oriented batch validation of all secrets (exit code 1 on failure, with or without --json; the bare --json shape is deprecated and moves to the { ok, data } wrapper in 1.0)

Options

-g, --global-p, --project--project-path <path>--json

Examples

qring ci:validate
$ qring ci:validate --project --json

qring policy

Show project governance policy summary (a corrupt .q-ring.json exits 1 and reports { policyError } with --json; the bare --json shape is deprecated and moves to the { ok, data } wrapper in 1.0)

Options

--json

Examples

qring policy
$ qring policy --json

qring doctor

Diagnose the q-ring installation - keyring backend round-trip, audit dir + hash chain, .q-ring.json validity (a corrupt file is reported, never a crash), policy, qring-mcp on PATH

Options

--project-path <path>--json

Examples

qring doctor
$ qring doctor
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
$ qring completion zsh > ~/.zsh/completions/_qring

qring canary plant <key>

Plant a fake credential that stores and reads like a real secret - any read fires a desktop alert and a tamper-evident audit event; refuses to overwrite a real secret without --force

Options

-f, --format <format>--value <value>--description <text>--push <target>--repo <owner/name>--vercel-env <envs>--force--json-g, --global-p, --project--team <id>--org <id>--project-path <path>

Examples

qring canary
$ qring canary plant AWS_SECRET_KEY --format aws
qring canary
$ qring canary plant GHP_BACKUP_TOKEN --format github-pat
qring canary
$ qring canary plant AWS_SECRET_ACCESS_KEY --format aws-secret --push github --repo you/your-app
qring canary
$ qring canary plant GITHUB_TOKEN --format github --project

qring canary list

List planted canaries and their trip counts

Options

--json-g, --global-p, --project--team <id>--org <id>--project-path <path>

Examples

qring canary
$ qring canary list
qring canary
$ qring canary list --json

qring canary disarm <key>

Clear the canary flag so reads stop alarming - the stored value stays fake until you overwrite it

Options

-g, --global-p, --project--team <id>--org <id>--project-path <path>

Examples

qring canary
$ qring canary disarm AWS_SECRET_KEY

qring canary alert <add|list|remove|enable|disable|test>

Webhook channels that receive canary trips - Discord, Slack, ntfy, or a generic JSON POST; SSRF-guarded, fire-and-forget, never carrying the fake value

Options

--discord <url>--slack <url>--ntfy <url>--url <url>--description <text>--json

Examples

qring canary
$ qring canary alert add --discord https://discord.com/api/webhooks/…
qring canary
$ qring canary alert add --ntfy https://ntfy.sh/my-canaries
qring canary
$ qring canary alert list
qring canary
$ qring canary alert test

qring mcp wrap [command...]

Proxy a third-party MCP server through the airlock - spawned with a stripped environment or dialed over Streamable HTTP; tools, resources, and prompts pass through; every call audited with a per-session correlation id (arguments never logged); known secret values, whole or encoded (never partial slices), replaced with [QRING:REDACTED:<KEY>] in results, errors and progress, and results withheld if redaction cannot be set up; policy.wrap enforced

Options

--url <url>--header <name:value>--auth-secret <KEY>--inherit-env--no-redact (keep results verbatim)--label <label>--project-path <path>

Examples

qring mcp
$ qring mcp wrap -- npx some-mcp-server
qring mcp
$ qring mcp wrap --url https://mcp.example.com/mcp --auth-secret EXAMPLE_MCP_TOKEN
qring mcp
$ qring mcp wrap --label "browser tools" -- npx @some/browser-mcp

qring mcp approve <tool>

Grant (or --revoke) a time-limited, HMAC-verified approval for a wrapped tool listed in policy.wrap.approveTools; bound to the project the airlock runs in

Options

--for <seconds>--reason <text>--revoke--project-path <path>

Examples

qring mcp
$ qring mcp approve github_merge_pr --for 900 --reason "release 1.4"
qring mcp
$ qring mcp approve github_merge_pr --revoke

qring mcp approvals

List live airlock tool approvals for this project

Options

--project-path <path>--json

Examples

qring mcp
$ qring mcp approvals

qring audit:sessions

Audit activity folded into per-agent sessions - one timeline per MCP client process or airlock session, with window, event and denial counts, and key names touched (never values)

Options

--agent <label>--since <when>-n, --limit <n>-v, --verbose--json

Examples

qring audit:sessions
$ qring audit:sessions
qring audit:sessions
$ qring audit:sessions --agent "Cursor@1.2.3" --since 7d --verbose
qring audit:sessions
$ qring audit:sessions --json