Getting Started

qring set <key> [value]

Store a secret (with optional quantum metadata)

$ 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)

$ qring get OPENAI_API_KEY --project --env prod

qring delete <key> (alias: rm)

Remove a secret from the keyring

$ qring delete LEGACY_TOKEN --project

qring list (alias: ls)

List all secrets with quantum status indicators

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

qring inspect <key>

Show full quantum state of a secret

$ qring inspect OPENAI_API_KEY --project

qring export

Export secrets as .env or JSON (collapses superposition)

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

qring import <file>

Import secrets from a .env file

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

qring check

Validate project secrets against .q-ring.json manifest

$ qring check --project-path .

qring validate [key]

Test if a secret is actually valid with its target service

$ 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)

$ qring exec --project --profile restricted --keys OPENAI_API_KEY -- node "scripts/smoke.js"

qring scan [dir]

Scan a codebase for hardcoded secrets

$ qring scan src --fix --project

qring lint <files...>

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

$ 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)

$ qring context --project --json

qring remember <key> <value>

Store a key-value pair in encrypted agent memory (persists across sessions)

$ qring remember deployment_note "rotate Stripe key after release"

qring recall [key]

Retrieve a value from agent memory, or list all keys

$ qring recall deployment_note
$ qring recall

qring forget <key>

Delete a key from agent memory

$ qring forget deployment_note

qring approve <key>

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

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

qring approvals

List all approval tokens with verification status

$ qring approvals

qring hook:install

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

$ qring hook:install --project-path .

qring hook:uninstall

Remove the q-ring pre-commit hook

$ qring hook:uninstall --project-path .

qring hook:run

Run the pre-commit secret scan (called by the git hook)

$ qring hook:run

qring wizard <name>

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

$ qring wizard stripe --keys STRIPE_KEY,STRIPE_WEBHOOK_SECRET --provider stripe --tags payments,prod

qring analyze

Analyze secret usage patterns and provide optimization suggestions

$ qring analyze --project

qring env

Show detected environment (wavefunction collapse context)

$ qring env --project-path .

qring generate (alias: gen)

Generate a cryptographic secret (quantum noise)

$ qring generate --format api-key --prefix sk- --save OPENAI_API_KEY --project

qring entangle <sourceKey> <targetKey>

Link two secrets — rotating one updates the other

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

qring disentangle <sourceKey> <targetKey>

Unlink two entangled secrets

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

qring tunnel create <value>

Create a tunneled secret (returns tunnel ID)

$ qring tunnel create "temp-token" --ttl 300 --max-reads 1

qring tunnel read <id>

Read a tunneled secret (may self-destruct)

$ qring tunnel read tu_abc123

qring tunnel destroy <id>

Destroy a tunneled secret immediately

$ qring tunnel destroy tu_abc123

qring tunnel list (alias: tunnel ls)

List active tunnels

$ qring tunnel list

qring teleport pack

Pack secrets into an encrypted bundle

$ qring teleport pack --project --keys OPENAI_API_KEY,STRIPE_KEY > bundle.qring

qring teleport unpack [bundle]

Unpack and import secrets from an encrypted bundle

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

qring audit

View the audit log (observer effect)

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

qring audit:verify

Verify the integrity of the audit hash chain

$ qring audit:verify

qring audit:export

Export audit events in a portable format

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

qring health

Check the health of all secrets

$ qring health --project

qring hook add

Register a new hook

$ 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

$ qring hook list

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

Remove a hook by ID

$ qring hook remove hk_abc123

qring hook enable <id>

Enable a hook

$ qring hook enable hk_abc123

qring hook disable <id>

Disable a hook

$ qring hook disable hk_abc123

qring hook test <id>

Dry-run a hook with a mock payload

$ qring hook test hk_abc123

qring env:generate

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

$ qring env:generate --project-path . --env prod -o .env

qring status

Launch the quantum status dashboard in your browser

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

qring agent

Start the autonomous agent (background monitor)

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

qring rotate <key>

Attempt issuer-native rotation of a secret via its provider

$ qring rotate OPENAI_API_KEY --project --provider openai

qring ci:validate

CI-oriented batch validation of all secrets (exit code 1 on failure)

$ qring ci:validate --project --json

qring policy

Show project governance policy summary

$ qring policy --json

get_secret

Retrieve `OPENAI_API_KEY` from project scope for `prod` and return just the raw value.

list_secrets

List project secrets tagged `payments` and show only stale entries matching `STRIPE_*`.

set_secret

Set `STRIPE_SECRET_KEY` in project scope with tags `payments,prod` and a TTL of 86400 seconds.

delete_secret

Delete `LEGACY_TOKEN` from global scope and confirm whether it existed.

has_secret

Check whether `GITHUB_TOKEN` exists in project scope and return true/false.

export_secrets

Export only `OPENAI_API_KEY` and `STRIPE_KEY` as `.env` for `prod`.

import_dotenv

Import this `.env` content into project scope in dry-run mode and report what would change.

check_project

Validate `.q-ring.json` at this path and show missing, stale, and expired required keys.

env_generate

Generate `.env` content from the project manifest for `staging` without writing files.

inspect_secret

Inspect `DB_PASSWORD` and summarize scope, decay state, tags, and entanglement metadata.

detect_environment

Detect current environment for this project path and include the detection source.

generate_secret

Generate an `api-key` with prefix `sk-` and save it as `OPENAI_API_KEY` in project scope.

entangle_secrets

Entangle `API_KEY` in this project with `API_KEY_BACKUP` in another project path.

disentangle_secrets

Remove entanglement between `API_KEY` and `API_KEY_BACKUP` and confirm success.

tunnel_create

Create an ephemeral tunnel value with TTL 300 and maxReads 1, then return the tunnel ID.

tunnel_read

Read tunnel `tu_abc123` once and return value or not-found/expired status.

tunnel_list

List all active tunnels with read counts and time remaining.

tunnel_destroy

Destroy tunnel `tu_abc123` immediately and confirm whether it existed.

teleport_pack

Pack keys `OPENAI_API_KEY` and `STRIPE_KEY` into an encrypted bundle using this passphrase.

teleport_unpack

Unpack this teleport bundle in dry-run mode and list keys and scopes that would be imported.

audit_log

Return last 100 `read` audit events for `OPENAI_API_KEY` in reverse chronological order.

detect_anomalies

Detect anomalies for `OPENAI_API_KEY` and include recommendations.

health_check

Run a project-scope health check and summarize healthy/stale/expired plus anomaly count.

validate_secret

Validate `OPENAI_API_KEY` with provider auto-detection and return provider + latency.

list_providers

List available validation providers with descriptions and known key prefixes.

register_hook

Register an HTTP hook for `DB_PASSWORD` rotate events to this URL with a clear description.

list_hooks

List all registered hooks and include type, match criteria, and enabled status.

remove_hook

Remove hook `hk_abc123` and return a not-found error if it does not exist.

exec_with_secrets

Run `node scripts/smoke.js` with only `OPENAI_API_KEY` injected using restricted profile.

scan_codebase_for_secrets

Scan `./src` for hardcoded secrets and return file, line, key name, and entropy.

get_project_context

Return redacted project context for this path including manifest and recent actions.

agent_remember

Remember the note `rotated Stripe keys after release` under key `release_notes`.

agent_recall

Recall key `release_notes`; if omitted, list all memory keys and update times.

agent_forget

Forget memory key `release_notes` and report whether it was present.

lint_files

Lint these files for hardcoded secrets in fix mode and return structured fix results.

analyze_secrets

Analyze project secrets for unused keys, stale entries, and top read frequency.

status_dashboard

Start dashboard on port 9876 and return the local URL to open in a browser.

agent_scan

Run one agent scan with auto-rotate enabled across these project paths and return report JSON.

verify_audit_chain

Verify audit hash-chain integrity and show first break location if tampering is detected.

export_audit

Export audit events as JSON from 2026-03-01 until now.

rotate_secret

Attempt provider-native rotation for `OPENAI_API_KEY` and store the new value if rotated.

ci_validate_secrets

Run CI batch validation for project scope and return pass/fail summary JSON.

check_policy

Check whether command `npm publish` is allowed by exec policy for this project path.

get_policy_summary

Return governance policy summary for this project, including tool and secret lifecycle rules.