Command line

The menu-bar app does everything most people need. The keychord command is for setup, passwords, checking your config, and your AI agent. Add it once (see Install, step 8); after that, run keychord --help for the list.

Passwords and secrets

Passwords never go in your YAML. They go in the encrypted vault (secrets.kcv, next to your config), and a chord uses them by name as ${secret:NAME}.

keychord password set WORK_PW   # asks for the value (hidden), saves it in the vault
keychord password ls            # lists the NAMES only, never the values
keychord password rm WORK_PW    # removes one secret from the vault
# `keychord secret set|ls|rm` does the same
keychord unlock                 # asks for the vault passphrase, keeps this Mac unlocked
keychord lock                   # forgets the key on this Mac; the next use asks again

The first password set creates the vault: it asks for a new passphrase (8+ characters, typed twice) and prints a recovery key. Write the recovery key down and keep it offline. Nobody can recover the secrets without the passphrase or that key.

Use the secret in a chord:

chords:
  - keys: lg
    text: "${work_email}{tab}${secret:WORK_PW}{enter}"

Note

Secret values are always typed, never pasted, never written to the log, and shown as •••• in previews. Fire a login chord in the username field: macOS blocks all typing tools (keychord included) inside password fields.

Check and explore your config

keychord check            # validates the config and every include; errors show file:line
keychord check --json     # the same, as JSON (for scripts and agents)
keychord list             # every chord: keys, kind, where it is defined
keychord explain lg       # what a chord does and where it fires
keychord vars             # every var and its value (secrets are not vars; they stay in the vault)

Set, rename and remove chords

keychord set em --text '${work_email}'               # add or update one chord, comments kept
keychord set sig --file snippets/sig.md              # a chord whose text lives in a file
keychord set lg --text '${me}{tab}${secret:WORK_PW}{enter}' --when chrome
keychord set ps --text 'docker ps{enter}' --in packs/dev.yml
keychord rename em mail                              # change a chord's keys
keychord rm mail                                     # comments it out with "# removed <date>"
keychord var set work_email ada@example.com          # add or update a var
keychord var rm work_email                           # comments it out

Every change is checked by loading your whole config. If it breaks something, the file is put back as it was and you get the error.

History: every change, and time travel

Every change to your config files is recorded in <config folder>/.history: changes from these commands, from the app (save chord, packs, super key), and edits you make by hand in an editor. Nothing is ever deleted.

keychord history              # newest first: id, time, file, what changed, and where from
keychord history --file packs/dev.yml -n 20
keychord show 42              # the diff of change 42
keychord restore 42           # writes that version back, as a NEW change
keychord undo                 # goes back to the version before the last change

Password values never enter history: it records “password set WORK_PW”, not the value. Snapshots are capped at 50 MB (set KEYCHORD_HISTORY_MAX_MB to change it). Only the oldest hand-edit snapshots are thinned; the log lines are kept forever.

Add and import chords (append only)

keychord add --keys em --text '${work_email}'   # appends a chord; never rewrites your lines
keychord import csv prompts.csv                 # format first: csv, json, md or espanso
keychord pack new team                          # starts packs/team.yml and includes it

add checks the config after writing. If the check fails, it puts the file back as it was. It refuses secret values: use keychord password set for those. Run keychord help for the full list.

Health and startup

keychord doctor           # permissions, config, vault, aos, start at login, speed
keychord doctor --json    # the same, as JSON
keychord doctor --fix     # opens the right Settings pane for each missing permission
keychord autostart on     # start at login (safe to run twice)
keychord autostart status
keychord autostart off
keychord --version

For troubleshooting

keychord bench 100        # measures chord → first character on this Mac
keychord chord tt         # fires chord tt as if you pressed it (into the front window)

Caution

keychord chord types into whatever window is in front. Use it in a new blank document only.