Getting Started

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 --raw
sk-proj-abc123...

# List all stored keys
$ qring list
OPENAI_API_KEY [dev] healthy 0 reads

# Run a health check
$ qring health

Next step: connect your AI editor — configure the MCP server for Cursor, Kiro, Claude Code, or VS Code.

1Where the secret went

qring set wraps the value in a small JSON envelope (the value, optional per-environment states, TTL, tags, access count) and writes it through @napi-rs/keyring as one keychain item. The service name encodes the scope: q-ring:global by default, q-ring:project:<hash> when you pass --project. The account is the key name.

• macOS: a generic password in the login keychain (~/Library/Keychains/login.keychain-db). Open Keychain Access and search for q-ring to see it.
• Windows: a generic credential in Credential Manager, encrypted with DPAPI under your account. Control Panel, Credential Manager, Windows Credentials lists it.
• Linux: an item in your Secret Service collection (GNOME Keyring, ksecretservice or KeePassXC), usually stored under ~/.local/share/keyrings/. Seahorse or secret-tool search can show it.

The files q-ring keeps under ~/.config/q-ring/ hold the audit log and the entanglement, approval and hook registries, created 0600. Secret values are never written there.

2What qring health and qring doctor check

qring health is about the secrets. It walks every key in scope and sorts them by TTL into healthy, stale (75 percent or more of the lifetime used), expired, and no decay set, then scans the audit log for access anomalies such as bursts or unusual hours. It does not test the keychain itself.

qring doctor is about the installation. It writes, reads and deletes a throwaway probe entry to prove the keychain backend works, confirms the audit directory is writable, looks for a .q-ring.json manifest and policy, flags approvals that predate project binding, and checks that qring-mcp is on PATH. Run it first when anything fails.

qring health --json
qring doctor --json

1Read a value into a script

--raw prints the bare value with no trailing newline, which is what command substitution wants. Without it, qring get prints a JSON object with key and value; --json wraps that in the { ok, data } shape every read command shares.

# Bare value, no trailing newline
OPENAI_API_KEY="$(qring get OPENAI_API_KEY --raw)"

# Structured output for tooling
qring get OPENAI_API_KEY --json
qring list --json

# Exit-code check, decay-aware (expired counts as absent)
qring has OPENAI_API_KEY --quiet && echo present

2Store without echoing

Omit the value and qring set prompts for it on stderr without echoing. When stdin is not a terminal it reads the value to EOF instead, so a pipe works in scripts. Existing .env files can be imported in bulk; --dry-run shows what would be written.

# Interactive prompt, nothing in shell history
qring set STRIPE_KEY

# Non-interactive: value arrives on stdin
printf '%s' "$VALUE" | qring set STRIPE_KEY

# Migrate a dotenv file, then delete it
qring import .env --skip-existing --dry-run
qring import .env --skip-existing

3Inject instead of print

Most scripts do not need the value in the shell at all; they need it in a child process. qring exec injects secrets into the environment of the command after -- and replaces any known secret value in the captured stdout and stderr before it reaches you. qring run is the narrower form: only keys declared in .q-ring.json or referenced as qring:// pointers in a .env file are injected.

# Every secret in scope, output redacted
qring exec -- pnpm test

# Only the keys you name
qring exec --keys DATABASE_URL,REDIS_URL -- pnpm run db:migrate

# Only what the project manifest declares
qring run -- node server.js
qring run --dry-run -- node server.js

Destructive commands such as qring delete ask for confirmation on a terminal and fail on non-interactive stdin; pass --yes in scripts.