q-ring 101 - store a secret (qring set)

Panduan

What it does

qring set stores a secret as one item in your operating system's credential store: Keychain on macOS, Secret Service on Linux, Credential Manager on Windows. The value goes inside a small JSON envelope (value, optional per-environment states, TTL, tags, access count) under a service name such as q-ring:global. qring list then shows what you have stored, by name and status, without printing a single value.

Try it

# Leave the value off and q-ring prompts for it without echoing
qring set OPENAI_API_KEY

# In a script, pipe it in instead of passing it as an argument
printf '%s' "$OPENAI_API_KEY" | qring set OPENAI_API_KEY

# Names, scope, and status only
qring list

# Read it back when a script needs it (bare value, no trailing newline)
qring get OPENAI_API_KEY --raw

Why it matters

A .env file is plaintext on disk. .gitignore keeps it out of a careful commit, but not out of git add -A after someone edits the ignore file, not out of cat when an agent builds context, and not out of a test that prints its config. A keychain item has no file to read or commit. It is encrypted at rest under your login and handed only to a process that asks for it. qring list lets you, or an agent, check what exists without the check itself leaking anything.

Gotchas and good to know

• Typing qring set KEY value with the value inline puts the secret in your shell history. Omit it and answer the prompt, or pipe it.
• Scope is part of the address. With no flag, secrets go to global scope (q-ring:global). Pass --project to keep a key per repository (q-ring:project:<hash>).
• Headless Linux and SSH sessions often have no Secret Service running, so set fails. The docs cover starting one with dbus-run-session, or opting into the encrypted file backend with QRING_BACKEND=file and QRING_FILE_PASSPHRASE. That backend never switches on by itself.
• If anything fails, run qring doctor first. It writes, reads, and deletes a throwaway probe entry to prove the keychain backend works.
• A keychain does not stop a process running as you from reading a value. It removes the accidental leak paths, which is where most leaks come from.

Go deeper

• Getting Started: where the secret went
• Using your OS keychain from the terminal
• CLI reference