KeyJar docs

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.

shell
$ 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.

shell, example output, fake keys
$ 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.

shell
$ 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.

shell
$ 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.

.env
ANTHROPIC_API_KEY=kj://anthropic/agent-lab
OPENROUTER_API_KEY=kj://openrouter/evals
DATABASE_URL=postgres://localhost/lab
shell
$ 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.

shell
$ 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.

shell
$ 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.

Linux
$ sha256sum --check --ignore-missing SHA256SUMS
macOS
$ 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.

kj://openrouter/evals
  • 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 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.

shell
$ kj run --env-file .env --env-file .env.production -- npm start

Exit codes

CodeMeaning
0Resolved
2Not 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
3No key has this provider and label, including a machine with no vault yet. Resolving never creates a vault.
4The vault cannot be read: no keychain, missing vault key, damaged file, or a file that needs a newer kj
5Valid reference that uses a feature this resolver does not support
1Anything 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.

Claude Code, ~/.claude/settings.json
{
  "apiKeyHelper": "kj get kj://anthropic/agent-lab"
}
Any tool that reads environment variables, for example Codex
$ 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

CommandWhat it doesStatus
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]... -- cmdSets 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 | deactivateActivates 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 | statusWhether KeyJar may ask each key's own provider for its dates. Off by default.Pro
kj ls, rotate, rm, agent, fetch, recovery, recover, restore-prevVault 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