aikeys configuration

Setup

aikeys setup                     # default store: file
aikeys setup --store keychain    # default store: native keychain
aikeys setup --force             # overwrite an existing config.json

setup creates the home directory with mode 0700, writes config.json with mode 0600, and creates an empty vault.json (mode 0600) only if one does not already exist. --store must be file or keychain. Running it again without --force fails. --force rewrites config.json with the defaults and leaves the vault and its entries alone. Setup does not ask for a password; the file store takes a password each time a secret is written or read.

Files and paths

aikeys where prints the resolved home, config and vault paths. The home directory gets mode 0700 when aikeys creates it. config.json, vault.json and rendered output are always written atomically at 0600: aikeys writes a new 0600 temporary file in the same directory and renames it over the target, so an existing file never keeps a looser mode, and a symlink at the target is replaced rather than followed.

Keychain or file vault

The store is chosen per write: set --store wins, then defaultStore from config.json, then file. A read uses whatever store the entry was written to, so one vault can mix both.

Keychain items are saved under the service name from keychainService (default aikeys) with the account section/key@version. Reads look the entry up in vault.json first, so a keychain item without a matching vault entry is not found.

There is no fallback between stores. If you ask for the keychain store on a system without security or secret-tool, the write fails and nothing is stored. The confirmation line names the store the secret was written to.

Keychain limits

The secret reaches security and secret-tool on stdin, never as a command-line argument. On macOS aikeys drives security -i and sends the value hex-encoded, which limits a keychain secret to roughly 1,900 bytes (less with long names); longer secrets are refused. Every keychain write is read back and compared, and on a mismatch the item is deleted and set fails, which in practice rejects values containing tabs or other non-printable characters. Keychain service and account names may only use letters, numbers, dot, underscore, dash, slash and @, so versions stored in the keychain are limited to those characters. Use the file store for anything outside these limits.

config.json reference

{
  "version": 1,
  "defaultStore": "file",
  "vaultFile": "vault.json",
  "keychainService": "aikeys",
  "template": {
    "tokenPattern": "{{aikeys:<section>/<key>@<version>}}",
    "examples": [
      "OPENAI_API_KEY={{aikeys:openai/api_key@prod}}",
      "ANTHROPIC_API_KEY={{aikeys:anthropic/api_key}}"
    ]
  },
  "agentPolicy": {
    "preferRender": true,
    "doNotPrintSecretsInLogs": true,
    "allowedCommands": [
      "aikeys get <section>/<key> [version]",
      "aikeys render <template> <output>"
    ]
  }
}

The file is plain JSON on purpose, so agents and scripts can read the conventions without running the CLI. Until it exists, set, get, render and scan --import fail with run `aikeys setup` first. where, help and a plain scan work without it.

vault.json reference

{
  "version": 1,
  "entries": {
    "openai/api_key": {
      "versions": {
        "prod": {
          "store": "file",
          "encrypted": {
            "alg": "aes-256-gcm",
            "kdf": "scrypt",
            "salt": "<base64, 16 bytes>",
            "iv": "<base64, 12 bytes>",
            "tag": "<base64, 16 bytes>",
            "ciphertext": "<base64>"
          },
          "updatedAt": "2026-09-28T12:24:51.206Z"
        }
      }
    },
    "github/token": {
      "versions": {
        "default": {
          "store": "keychain",
          "account": "github/token@default",
          "updatedAt": "2026-09-28T12:30:02.114Z"
        }
      }
    }
  }
}

Secret names, versions, store types and timestamps are stored in clear text. Only the values are encrypted. Do not edit this file by hand.

Commands and flags

aikeys setup [--store file|keychain] [--force]
aikeys set <section>/<key> [version] [--store file|keychain]
aikeys get <section>/<key> [version]
aikeys render <template> <output>
aikeys scan <dir-tree> [--import]
aikeys where
aikeys help

Flags may appear anywhere after the command. --store takes a value, which must be file or keychain for both setup and set; any other value is an error.

Environment variables

These are the only variables aikeys reads.

How secrets and passwords are read

Each prompt resolves its input in this order:

stdin is read to the end and trailing whitespace, including the final newline, is removed. It can only be read once, so when you pipe the secret into set for the file store, pass the password in AIKEYS_PASSWORD. The secret is read before the password.

The vault password is asked for once per process, so rendering a template with several file-store placeholders prompts once. Every entry has its own salt, and nothing checks that all entries share one password.

Template syntax

{{aikeys:section/key@version}}
{{aikeys:section/key}}          # version "default"

Placeholders can appear anywhere in any text file, any number of times. Text outside placeholders is copied unchanged.

Secret names and versions

Scanner rules

The scanner skips .git, node_modules and .apikeys directories, symbolic links, files over 2 MiB, files containing a NUL byte, and files ending in .png, .jpg, .jpeg, .gif, .pdf, .zip, .gz, .tar, .ico, .woff or .woff2. Values are masked as the first four and last four characters, or all asterisks when eight characters or fewer.

With --import, each finding is stored as scan/<file>-<name>-<n>@imported in the default store, where the file path is lowercased with other characters replaced by dashes and n numbers the findings in order.

Policy options

The agentPolicy block in config.json is guidance for agents that read the file. The CLI does not enforce it: it cannot tell an agent from a person, and it does not check commands against allowedCommands. The first time it reads a config containing the block, it prints a one-time notice to stderr saying so.

What the CLI does enforce

To restrict an agent for real, give it a shell without write access to the aikeys home, or keep file-store secrets behind a password the agent does not have.

Exit codes