Spec, version 1
kj:// reference, version 1
A kj:// reference is a string that names a stored API
key without containing it. It is safe to commit, paste and copy into
worktrees. This document is the public contract. Any tool may write
references and may resolve them by calling kj.
Grammar
reference = "kj://" provider "/" label provider = slug label = slug slug = start *62( start / "." / "_" / "-" ) start = %x61-7A / DIGIT ; a-z 0-9
Examples: kj://openai/work,
kj://anthropic/main,
kj://mistral/acme-api.
Rules
- One spelling. Lowercase only. No percent-encoding,
no case folding, no trailing slash, no surrounding whitespace. A
resolver compares bytes.
grep -r 'kj://openai/work'finds every use. - Identity is
(provider, label). A reference has no project, path, vault id or version. One key used in 138 files is one string. - Any slug is a valid provider. KeyJar's provider
table adds detection and metadata for the providers it knows. A key from
an unknown provider is stored under the slug the user picks, or
other. - Renames do not break references. When a label changes, the old label stays as an alias of the same key and keeps resolving. A vault refuses a new label that equals another key's label or alias for the same provider.
- The reference is the whole value.
OPENAI_API_KEY=kj://openai/workis a reference.URL=https://x/?key=kj://openai/workis plain text and passes through unchanged. Surrounding dotenv quotes are stripped before the check. A value that starts withkj://and is not a valid reference is an error, not plain text. - Unknown syntax stops the resolver. Version 1
defines no
?queryand no#fragment. A resolver that meets a valid reference followed by either one exits with code 5 and resolves nothing. Later versions add features only through those two positions, so a version 1 resolver never returns the wrong key for a newer reference. The part before the first?or#must itself be a valid version 1 reference. If it is not, the exit code is 2. - A reference never reaches a program.
kj runresolves every reference before it starts the child. If one fails, the child does not start.
Resolver contract
kj get <reference> writes the key and one newline
to stdout and exits 0. It writes nothing else to stdout.
kj run [--env-file <path>]... -- <command>
reads env files and the current environment, resolves every value that
is a reference, and starts the command. On Unix it replaces itself with
the command.
- Only references are set.
kj runsets a variable only when its value is a reference, to the key. It never sets a plain value, with or without--env-file. Every other variable in the files is left to the command's own loader, which decides precedence between files,${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 regular file named.envor.env.*directly in the working directory, except*.kj-tmpand a name that ends in.example,.sampleor.template. A file that cannot be read is skipped with a warning. If a variable holds 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 the command's loader knows which file wins. An empty value and a reference to another key both count as another value. The same reference in several files is accepted. A reference is set only when.envor.env.localholds it. A variable whose reference is only in other files, such as.env.production, also stops the command with exit code 2, because the command's loader reads those files only in some modes. The message names the files and prints the--env-filearguments for that mode. A variable set in the environment is not checked. - With
--env-fileit reads only the named files, a later one over an earlier one, and neither rule applies. A named file that cannot be read stops the run with exit code 1.
Values are read as VAR=value with an optional
export, one pair of surrounding quotes and a
# comment. Only a value that would be set is checked as a
reference.
| Exit code | Meaning |
|---|---|
| 0 | Resolved |
| 2 | Not a valid reference, or kj run found a variable as a
reference in one env file and as another value in another, or only in an
env file that is read in some modes |
| 3 | No key has this provider and label. This includes a machine with no vault yet: resolving never creates one |
| 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 it never repeats the text that was passed as a reference, because people paste keys by mistake.
What a reference does not promise
Resolving puts the real key in the child's environment or on stdout. A process running as the same OS user can read both. A reference keeps the key out of files. It does not keep the key from an agent that runs as you.
Stability
Rules 1 to 7, the grammar and the exit codes do not change within version 1. Provider slugs that KeyJar ships are never renamed.