Recipes¶

Task-first snippets for the situations notenv shows up in. Each one is the short version; the link takes you to the guide with the full artifact and the reasoning.

Solo developer¶

Start with a local vault¶

No accounts, no rclone, one passphrase.

notenv setup                   # local vault (the default)
cd my-project && notenv init   # writes notenv.toml (commit it)
notenv import .env && rm .env  # or: notenv set KEY one at a time
notenv run -- npm run dev      # secrets injected for this process only

→ Quick start

Use a cloud remote instead¶

Run notenv setup and choose the cloud option; notenv walks you through selecting or creating an rclone remote (Backblaze B2, S3, SFTP, WebDAV, anything rclone speaks).

→ Cloud remotes

Move a local vault to a remote¶

Same vault afterward, nothing re-encrypted, every credential still works.

notenv vault copy

→ Cloud remotes

Set up on another of your machines¶

git clone <your-project> && cd <your-project>
notenv setup                   # enter your escrowed passphrase
notenv run -- ...              # ready

→ On a new machine

Teams¶

Onboard a teammate¶

notenv key add alice           # prints a one-time onboarding string; send it over a private channel

Alice points her machine at the same storage, runs notenv setup, and enters the string; her first command replaces it with a passphrase only she knows.

→ Share a vault with your team

Offboard a teammate or machine¶

key rm removes the slot and re-keys the vault (fresh master, every secret re-encrypted), so the removed credential decrypts nothing new. Then rotate the storage credential at your provider, which notenv cannot do for you.

notenv key rm alice            # re-keys automatically; surviving slots keep working
# then: rotate the bucket/SFTP credential at your provider

→ Share a vault with your team

Change a passphrase, or re-key as a precaution¶

notenv key rotate              # rewraps your slot (header only; secrets untouched)
notenv key rotate-master       # fresh master, every secret re-encrypted, all slots kept

→ Share a vault with your team

AI agents¶

A shell agent (skill or AGENTS.md)¶

Install the agent skill into your agent's skill location, or drop the short block from the guide into AGENTS.md / CLAUDE.md. The agent runs work with notenv run -- <cmd> and discovers secrets with notenv list, never seeing a value.

→ AI agents

An agent over MCP¶

claude mcp add notenv -- notenv mcp        # or any MCP client, stdio transport

For a JSON-configured client, see the mcp.json entry. Four read/exec tools, none of which returns a secret value.

→ AI agents

Operations¶

Check a vault's health¶

Read-only; names any recoverable problem state and the way out.

notenv doctor

→ Recover from problems

Pull a change made on another machine¶

notenv run --refresh -- ...    # bypass the local cache for this run

→ Caching

Recover after a lost or dead machine¶

Nothing to restore but your passphrase: it lives in your password manager, not on the storage. On a new machine, git clone, notenv setup, and you are back.

→ On a new machine

Rotate after a suspected compromise¶

notenv key rotate-master       # fresh master; anything captured stops decrypting new writes
# then: rotate the storage credential at your provider

→ Share a vault with your team

Export your secrets, or delete a vault¶

notenv export > backup.env     # one namespace; --all for the whole vault
notenv vault delete <name>     # destroy a vault you no longer want (asks the passphrase)

→ Export or delete a vault

A secret will not decrypt¶

notenv run --skip-corrupt -- ...   # read the one-generation backup
notenv key evict <namespace>       # rebuild from what survives (last resort)

→ Recover from problems