Quickstart
Your keys in one jar, in five commands.
Install the CLI, find the keys already on your machine, move them into the vault, and run your tools with kj:// references instead of plaintext.
What works today. kj scan, kj import, kj undo, kj add, kj get, kj run, kj license and the tray app. Pro auto-fill and reminders, marked Pro, work too.
1. Install
The CLI is one binary. macOS and Linux. The tray app is a separate download. Check the file against its published checksum before you run it, see Verify a download.
$ curl -fsSL https://keyjar.dev/install | sh
2. Find what is already on disk
kj scan walks your home folder, or the paths you name, and groups every hit by key. It changes nothing.
$ kj scan ANTHROPIC sk-ant-api03-••••Xq4f 138 files OPENROUTER sk-or-v1-••••8d21 9 files … 22 keys across 386 locations $ kj scan ~/code # only this folder $ kj scan --json # machine-readable report
On a terminal, kj scan ends by asking whether to import. Without one, it prints To import these keys, run: kj import.
3. Import, and undo if you need to
kj import stores each key in the vault. It then offers to replace each .env line whose whole value is the key with a reference. You answer per file: y replaces, n leaves the file, a accepts this and every later file, q stops with nothing changed. Every other copy (shell history, JSON, source) is listed for you to clean up by hand.
$ kj import # review each file $ kj import --yes ~/code # no prompt, for scripts $ kj undo # list imports that replaced values $ kj undo <batch> # write that import's values back
kj undo puts the plaintext values back in the files, so use it only to recover from a bad rewrite. Removing a value from a file does not remove it from git history.
4. Add a key the moment you create it
kj add reads the key from a hidden prompt, or from stdin. It never takes the key as an argument, because an argument is visible to every process and to shell history. The tray app has the same thing on Ctrl+Shift+K, except on Wayland, where apps cannot register global shortcuts.
$ kj add openai/work $ pbpaste | kj add openai/work # macOS; use xclip -o on Linux
5. Run with references
Put refs in .env. kj run resolves them into the child process's environment at start. The file on disk keeps the ref.
ANTHROPIC_API_KEY=kj://anthropic/agent-lab OPENROUTER_API_KEY=kj://openrouter/evals DATABASE_URL=postgres://localhost/lab
$ kj run -- npm run dev
Only the two kj:// values are set. DATABASE_URL is left to your app's own .env loader. Details are in the next section.
6. Pro license
After you buy Pro, enter the license key at a hidden prompt, or on stdin. It is never read from an argument.
$ kj license activate $ kj license status
Pro adds auto-fill and reminders, labelled Pro. The free app does not depend on them.
Auto-fill is off until you allow it. The first time it could run, KeyJar asks once. kj autofill on, off and status change the answer, and KJ_NO_AUTO_FILL=1 stops it whatever the answer is. When it is on, a key is sent only to the provider that issued it. See where your data goes.
$ kj autofill status $ kj remind $ kj remind --check
Reminders fire 14, 3 and 0 days before a key expires and after 90 days idle, as one summary notification. Report problems or ask for things on GitHub issues.
Verify a download
Each release is a set of binaries and a SHA256SUMS file that lists the SHA-256 checksum of every file. Download the binary and SHA256SUMS from the GitHub releases page, then check the file before you run it.
$ sha256sum --check --ignore-missing SHA256SUMS
$ shasum -a 256 --check --ignore-missing SHA256SUMS
A good file prints OK next to its name. Anything else means the file is not the one that was published: delete it and download again.
What a checksum proves. It proves the file matches the published list, so it catches a corrupted or swapped download. If the checksum file is served from the same place as the binary, someone who can replace one can replace the other. Compare it with the checksum shown on a second page, such as the release announcement, when you can.
kj:// references
A reference names a key without containing it. It is safe to commit, paste into a config, or show an agent. Anything that can call kj can resolve one.
- Provider. A lowercase slug. Any slug is valid, so unknown providers work.
- Label. Your name for the key. Lowercase letters, digits,
.,_and-. Renaming keeps the old label as an alias.
Rules that matter day to day
- The reference must be the whole value.
URL=https://x/?key=kj://openai/workis plain text and passes through unchanged. - A value that starts with
kj://but is not valid is an error, never plain text. kj runresolves every reference before it starts the command. If one fails, the command does not start, and a program never receives a literalkj://string.- Version 1 defines no
?queryor#fragment. A resolver that sees one stops with exit code 5 rather than return the wrong key.
The full contract is the public kj:// reference spec. The file format is in the vault format spec.
kj run and env files
kj run [--env-file path]... -- command sets a variable only when its value is a reference, and sets it to the key. It never sets a plain value. Every other variable is left to the command's own loader (Next.js, Vite, dotenv and so on), which decides precedence, ${VAR} expansion and escapes.
- The environment wins. A variable already set in the environment is never overridden by a file. If its value there is a reference, that reference is resolved.
- With no
--env-fileit reads every file named.envor.env.*in the working directory, except*.kj-tmpand names ending in.example,.sampleor.template. - It refuses ambiguity. If a variable is a reference in one file and any other value in another,
kj rundoes not start the command. It exits 2 and names the variable and the files, because only your command's loader knows which file wins. - Mode files. A reference counts only when
.envor.env.localholds it. If a variable's reference is only in a file such as.env.production, which your loader reads in some modes,kj runexits 2. The message prints the--env-filearguments for that mode. - With
--env-fileit reads only the named files, a later one over an earlier one, and the two refusals above do not apply. A named file that cannot be read stops the run with exit code 1.
$ kj run --env-file .env --env-file .env.production -- npm start
Exit codes
| Code | Meaning |
|---|---|
| 0 | Resolved |
| 2 | Not a valid reference, or kj run found a variable that is a reference in one env file and another value in another, or only in a file read in some modes |
| 3 | No key has this provider and label, including a machine with no vault yet. Resolving never creates a vault. |
| 4 | The vault cannot be read: no keychain, missing vault key, damaged file, or a file that needs a newer kj |
| 5 | Valid reference that uses a feature this resolver does not support |
| 1 | Anything else |
Error text goes to stderr. It never contains key material and never repeats what you passed as a reference, because people paste keys by mistake.
Agent helper snippets
Each tool already has a way to get a key from a command or the environment. KeyJar plugs into that hook.
{
"apiKeyHelper": "kj get kj://anthropic/agent-lab"
}$ OPENAI_API_KEY=kj://openai/agent-lab kj run -- codex
Setups for other agents are planned once their key hooks are verified against their own documentation.
What this does and doesn't do. These hooks keep the key out of config files. The agent process still receives the real key, so it can read it and could print it. See the threat model.
CLI: kj
| Command | What it does | Status |
|---|---|---|
kj get <kj://provider/label> | Prints the key and one newline to stdout. This is what agent helpers call. | works today |
kj run [--env-file path]... -- cmd | Sets every variable whose value is a reference, then starts cmd. Refuses ambiguous env files. | works today |
kj scan [--json | --yes] [path...] | Finds keys under your home folder or the given paths. Offers to import on a terminal. | works today |
kj import [--yes] [path...] | Stores the keys it finds and replaces .env values with references, after you approve. | works today |
kj undo [batch] | Lists imports that replaced values, or writes one import's values back. | works today |
kj add [provider/label] | Adds one key, read from a hidden prompt or stdin. | works today |
kj license activate | status | deactivate | Activates a Pro license key, read from a hidden prompt or stdin. | works today |
kj remind [--check] | Lists due expiry and idle reminders. --check is for cron or launchd. | Pro |
kj autofill on | off | status | Whether KeyJar may ask each key's own provider for its dates. Off by default. | Pro |
kj ls, rotate, rm, agent, fetch, recovery, recover, restore-prev | Vault listing and removal, agent setup, provider metadata fetch, and recovery from a lost keychain entry. The tray app lists and edits keys meanwhile. | not built yet |