q-ring 101 - one key, every environment (qring inspect)

Guia

What it does

One q-ring secret can hold a separate value for each environment under a single key name. qring set API_KEY --env dev writes the dev state; repeat it with --env staging and --env prod. When something reads API_KEY, q-ring resolves the right state for the current context. q-ring calls this superposition, and the read is the collapse. qring inspect shows the shape of the key (which environments exist, the default, tags, decay, entanglement links) without printing any value.

Try it

qring set API_KEY --env dev        # prompts for each value
qring set API_KEY --env staging
qring set API_KEY --env prod

qring inspect API_KEY              # states and metadata, no values
qring env                          # which environment q-ring detects here

QRING_ENV=staging qring get API_KEY --raw
qring get API_KEY --env prod --raw

The environment is picked in this order: the --env flag, QRING_ENV, NODE_ENV, the git branch, the env field in .q-ring.json, and finally the secret's default.

Why it matters

Three environments usually means three key names (API_KEY_DEV, API_KEY_PROD) or three .env files, and sooner or later a prod value ends up in a dev run or the wrong file. One name with explicit states keeps your code identical across stages and makes the environment a property of where you run, not of which file you happened to load. Because inspect never prints values, you can review the setup on a shared screen, and an agent can check it over MCP with the inspect_secret tool without seeing a secret.

Gotchas and good to know

• Branch detection is opinionated: main or master resolves to prod, and develop to dev, unless a flag or variable earlier in the order says otherwise. If you work on main but mean dev, set QRING_ENV or pass --env. A branchMap in .q-ring.json maps your own branch names.
• When a value surprises you, run qring env first to see which environment q-ring detected.
• To compare stages, qring diff staging prod reports each key as same, different, or missing on one side, statuses only, and exits 1 on drift so it works as a CI gate. qring promote KEY --from staging --to prod copies one state into another instead of a copy-paste, and asks before overwriting a different value.
• Pair states with --ttl so an environment you only needed for a week expires on its own.

Go deeper

• CLI reference
• Getting Started
• MCP setup and cookbook