q-ring 101 - leave .env behind (qring import)

Guia

What it does

qring import <file> parses a .env file and stores every variable in it as a q-ring secret in your OS keychain. It understands standard dotenv syntax, including comments, quoted values, and escape sequences. After that the file has no job left, so you delete it, and the keys keep working through qring get, qring exec, or qring run.

Try it

# Preview: what would be imported, nothing written
qring import .env --dry-run

# Import into this project's scope, leaving existing keys alone
qring import .env --project --skip-existing

# Import a stage-specific file into one environment state
qring import .env.staging --project --env staging

# Check, then remove the file
qring list --project
rm .env

To keep the familiar workflow, run your dev server through qring exec -- npm run dev. If a tool insists on reading a .env, commit qring:// references in it instead of values (for example DATABASE_URL=qring://project/DATABASE_URL) and start the tool with qring run.

Why it matters

A gitignored .env is still plaintext that any process running as you can read. The common leak paths are mundane: git add -A after the ignore file changes, an agent running cat .env to debug a failing call, an .env.example built by copying the real file. Moving the values into the keychain removes the file those paths depend on, without renaming a single variable in your code.

Gotchas and good to know

• Without --project, keys go to global scope. If two repositories both have a DATABASE_URL, import each with --project from its own directory so they do not overwrite each other.
• --skip-existing protects keys you have already stored. Without it, matching names are overwritten with the file's values.
• Deleting the file does not clean history. If the .env was ever committed, the values are still in git, and those keys should be rotated.
• The import_dotenv MCP tool only accepts raw content and never reads files from disk, so an agent cannot use it to read arbitrary local files.
• Need a real .env again, for a tool that cannot do without one? qring env:generate writes one from your .q-ring.json manifest. Treat that output as a secret and delete it when you are done.

Go deeper

• Why .env files stop being safe once an agent can read them
• Getting Started: store without echoing
• CLI reference