Getting Started
Three steps to quantum-secured secrets: install, store, and integrate. Then dive into the 49-command CLI reference and the MCP cookbook.
Step 1 → 4
Quick start
From npm install to MCP-wired editor in under three minutes.
1Install q-ring
Pick your package manager and install globally:
$ pnpm add -g @i4ctime/q-ring
$ npm install -g @i4ctime/q-ring
$ yarn global add @i4ctime/q-ring
$ bun add -g @i4ctime/q-ring
$ brew install i4ctime/tap/qring
2Store your first secret
Secrets are stored in your OS-native keyring (macOS Keychain, Windows Credential Vault, or Linux Secret Service):
# Store a secret $ qring set OPENAI_API_KEY sk-proj-abc123... # Retrieve it $ qring get OPENAI_API_KEY sk-proj-abc123... # List all stored keys $ qring list OPENAI_API_KEY [dev] healthy 0 reads # Run a health check $ qring health
3Configure MCP
Add q-ring as an MCP server so AI agents can manage secrets natively. Same single binary, every host.
Cursor / Kiro
{
"mcpServers": {
"q-ring": {
"command": "qring-mcp"
}
}
}Claude Code
{
"mcpServers": {
"q-ring": {
"command": "qring-mcp"
}
}
}VS Code
{
"servers": {
"q-ring": {
"command": "qring-mcp"
}
}
}4Cursor Plugin (optional)
The q-ring Cursor Plugin bundles rules, skills, agents, slash commands, hooks, and the MCP connector — pre-wired to the 44 tools.
3 Rules
Always-on guidance for secret hygiene, q-ring workflow, and .env safety.
5 Skills
Auto-triggered: management, scanning, rotation, exec, onboarding.
2 Agents
Security auditor and day-to-day secret-ops assistant.
8 Commands
Slash commands for scan, rotate, validate, exec, teleport, and more.
2 Hooks
After-file-edit scan and session-start project context.
MCP Connector
Auto-connects to qring-mcp — all 44 tools available.
# Install from Cursor marketplace, or manually: $ cp -r cursor-plugin/ ~/.cursor/plugins/qring/
Reference
CLI complete reference
Every CLI command and option is listed below with at least one real invocation example. 49 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 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 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
No command-specific 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
No command-specific 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
No command-specific 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
No command-specific 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
No command-specific 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
MCP cookbook
Prompt cookbook
Every MCP tool with a one-sentence prompt example you can paste into any agent chat.
get_secretRetrieve `OPENAI_API_KEY` from project scope for `prod` and return just the raw value.
list_secretsList project secrets tagged `payments` and show only stale entries matching `STRIPE_*`.
set_secretSet `STRIPE_SECRET_KEY` in project scope with tags `payments,prod` and a TTL of 86400 seconds.
delete_secretDelete `LEGACY_TOKEN` from global scope and confirm whether it existed.
has_secretCheck whether `GITHUB_TOKEN` exists in project scope and return true/false.
export_secretsExport only `OPENAI_API_KEY` and `STRIPE_KEY` as `.env` for `prod`.
import_dotenvImport this `.env` content into project scope in dry-run mode and report what would change.
check_projectValidate `.q-ring.json` at this path and show missing, stale, and expired required keys.
env_generateGenerate `.env` content from the project manifest for `staging` without writing files.
inspect_secretInspect `DB_PASSWORD` and summarize scope, decay state, tags, and entanglement metadata.
detect_environmentDetect current environment for this project path and include the detection source.
generate_secretGenerate an `api-key` with prefix `sk-` and save it as `OPENAI_API_KEY` in project scope.
entangle_secretsEntangle `API_KEY` in this project with `API_KEY_BACKUP` in another project path.
disentangle_secretsRemove entanglement between `API_KEY` and `API_KEY_BACKUP` and confirm success.
tunnel_createCreate an ephemeral tunnel value with TTL 300 and maxReads 1, then return the tunnel ID.
tunnel_readRead tunnel `tu_abc123` once and return value or not-found/expired status.
tunnel_listList all active tunnels with read counts and time remaining.
tunnel_destroyDestroy tunnel `tu_abc123` immediately and confirm whether it existed.
teleport_packPack keys `OPENAI_API_KEY` and `STRIPE_KEY` into an encrypted bundle using this passphrase.
teleport_unpackUnpack this teleport bundle in dry-run mode and list keys and scopes that would be imported.
audit_logReturn last 100 `read` audit events for `OPENAI_API_KEY` in reverse chronological order.
detect_anomaliesDetect anomalies for `OPENAI_API_KEY` and include recommendations.
health_checkRun a project-scope health check and summarize healthy/stale/expired plus anomaly count.
validate_secretValidate `OPENAI_API_KEY` with provider auto-detection and return provider + latency.
list_providersList available validation providers with descriptions and known key prefixes.
register_hookRegister an HTTP hook for `DB_PASSWORD` rotate events to this URL with a clear description.
list_hooksList all registered hooks and include type, match criteria, and enabled status.
remove_hookRemove hook `hk_abc123` and return a not-found error if it does not exist.
exec_with_secretsRun `node scripts/smoke.js` with only `OPENAI_API_KEY` injected using restricted profile.
scan_codebase_for_secretsScan `./src` for hardcoded secrets and return file, line, key name, and entropy.
get_project_contextReturn redacted project context for this path including manifest and recent actions.
agent_rememberRemember the note `rotated Stripe keys after release` under key `release_notes`.
agent_recallRecall key `release_notes`; if omitted, list all memory keys and update times.
agent_forgetForget memory key `release_notes` and report whether it was present.
lint_filesLint these files for hardcoded secrets in fix mode and return structured fix results.
analyze_secretsAnalyze project secrets for unused keys, stale entries, and top read frequency.
status_dashboardStart the live status dashboard on port 9876 and return the local URL — page surfaces KPIs, manifest gaps, policy posture, approvals, hooks, anomalies, and a filterable 24h audit feed without ever rendering secret values.
agent_scanRun one agent scan with auto-rotate enabled across these project paths and return report JSON.
verify_audit_chainVerify audit hash-chain integrity and show first break location if tampering is detected.
export_auditExport audit events as JSON from 2026-03-01 until now.
rotate_secretAttempt provider-native rotation for `OPENAI_API_KEY` and store the new value if rotated.
ci_validate_secretsRun CI batch validation for project scope and return pass/fail summary JSON.
check_policyCheck whether command `npm publish` is allowed by exec policy for this project path.
get_policy_summaryReturn governance policy summary for this project, including tool and secret lifecycle rules.
Ready to explore more features?