Command line¶
Every command keryx takes, and what its --help says. Each one also takes --help, which
prints the same in the terminal. Hidden commands and options, kept only for units an older
build installed, are left out.
keryx¶
Keryx voice agent.
$ keryx [OPTIONS] COMMAND [ARGS]...
--version: Print the installed version and exit.--install-completion: Install completion for the current shell.--show-completion: Show completion for the current shell, to copy it or customize the installation.
keryx serve¶
Run Keryx: the Twilio phone server.
$ keryx serve [OPTIONS]
--demo: Try the phone before a coding agent is set up: every task comes back with a sample answer, and no agent tokens are spent.--host <str>: Override HOST for the phone server.--port <int>: Override PORT for the phone server.
keryx restart¶
Restart the Keryx service; it phones back by itself once it is up again.
$ keryx restart [OPTIONS]
--reason <str>: Why, in a few words; you hear it back on the call.--force: Restart even while a call is in progress.--no-callback: Restart quietly, with no call afterwards.--status: Print how the last restart went, and exit.
keryx upgrade¶
Update Keryx to the latest release, and restart the service onto it.
$ keryx upgrade [OPTIONS]
keryx loopback¶
Run one session from a WAV file: the dev harness for the provider without a mic.
$ keryx loopback [OPTIONS]
--wav <file>: 16-bit WAV to play at the model. [required]--out <path>: Where to write the reply audio. [default: reply.wav]--tail-seconds <float>: Seconds of silence to feed after the file. [default: 8.0]
keryx tools¶
List your own voice tools (DATA_DIR/tools) and any file the next call would refuse.
The same load a call makes, against every built-in tool's name, so a name clash or a file that will not import shows up here first. Exits 1 when anything was refused. A new or edited tool is offered from the next call, with no restart.
Nothing of the service's is built here: a subagent runs this inside the live service's environment, and the application's own objects own its socket and its records.
$ keryx tools [OPTIONS]
--json: Print it as one JSON document.
keryx forget¶
Delete call transcripts and finished task rows, now.
The same rules as the automatic retention pass, run on demand and regardless of whether
TRANSCRIPT_RETENTION_DAYS / TASK_RETENTION_DAYS are set. In particular the one that
matters: a finished task Keryx has not told you about yet is never deleted,
however old it is, because reported_at is the only record that you heard the result.
Those are reported as kept rather than removed silently.
This is not undoable, and --older-than 0 really does mean everything.
$ keryx forget [OPTIONS]
-d, --older-than <int range>: Delete transcripts and finished tasks older than this many days. 0 = all. [default: 0; x>=0]--transcripts-only: Leave the task rows alone.--tasks-only: Leave the call transcripts alone.-y, --yes: Do not ask first.
keryx doctor¶
Check that this machine is set up to run Keryx; exits non-zero on a hard failure.
$ keryx doctor [OPTIONS]
--json: Print every check as JSON and nothing else.--fix: Make every secret file owner-only first. Nothing else.
keryx setup¶
Set Keryx up: a guided walk through only what is still missing.
Everything it saves goes to KERYX_HOME as you go, so stopping part way loses nothing. A coding agent setting Keryx up uses the commands instead: --agent-instructions.
$ keryx setup [OPTIONS]
--all: Walk every section, and ask again about what is set.--agent-instructions: Print how a coding agent sets Keryx up from the command line, and exit.
keryx approvals¶
What the approval bridge has done, and the kill switch that stops it.
The switch is a file, deliberately: it is checked afresh on every single request, so it takes effect on the next prompt with no restart and without editing any settings — and it still works when the thing you want to stop is the thing you would have to ask.
$ keryx approvals [OPTIONS]
-n, --limit <int>: How many of the most recent lines to show. [default: 20]--disable: Stop the bridge escalating anything, now.--enable: Undo --disable.--install-hook: Install the hook into Claude Code.--uninstall-hook: Take the hook out of Claude Code.
keryx tasks¶
Inspect the tasks handed to subagents.
$ keryx tasks [OPTIONS] COMMAND [ARGS]...
keryx tasks list¶
List recent tasks, newest first.
$ keryx tasks list [OPTIONS]
--status <queued|running|done|failed|cancelled|all>: Only show tasks in this status. [default: all]--limit <int>: How many tasks to show. [default: 20]--internal: Also show Keryx's own housekeeping (the per-call memory updates).
keryx tasks show¶
Show everything stored about one task, including its report.
$ keryx tasks show [OPTIONS] {task_id}
task_id: The task id to show. [required]
keryx tasks usage¶
What the tasks spent, per project: tokens and the agents' own cost estimates.
$ keryx tasks usage [OPTIONS]
--days <int range>: Tasks created in the last N days; 0 for all of them. [default: 30; x>=0]--json: Machine-readable output.
keryx config¶
Read and change Keryx's settings (KERYX_HOME/config.toml and secrets.toml).
$ keryx config [OPTIONS] COMMAND [ARGS]...
keryx config list¶
Every setting: whether it is set, where from, and whether the service may change it.
A secret's value is never shown — only whether it is set.
$ keryx config list [OPTIONS]
--json: Print JSON and nothing else.--group <str>: Only one group: voice, agents, owner, phone, google, plugins, projects, approvals, limits, service, debug.
keryx config get¶
Print the value a setting has now, from wherever it comes. Never a secret's.
$ keryx config get [OPTIONS] {keys}...
keys...: One or more settings, by name. [required]--shell: Print KEY='value' lines a shell can eval.
keryx config set¶
Change settings. A secret's value is taken only from --stdin or --from-env.
Never on the command line, where ps and the shell's history keep it. Run inside a
Keryx task, this acts as the running service, and may change only what that is allowed
to (keryx config list).
$ keryx config set [OPTIONS] {pairs}...
pairs...: KEY VALUE [KEY VALUE …], or one KEY. [required]--stdin: Read the one KEY's value from standard input.--from-env <str>: Take the one KEY's value from this variable.
keryx config unset¶
Remove settings from the store, so the default (or the environment) applies again.
$ keryx config unset [OPTIONS] {keys}...
keys...: The settings to return to their default. [required]
keryx config path¶
Print where the configuration, the data, the state and the cache live.
$ keryx config path [OPTIONS]
--shell: Print NAME='path' lines a shell can eval, and nothing else.
keryx config lock¶
Stop the running service changing KEY.
$ keryx config lock [OPTIONS] {key}
key: The setting. [required]
keryx config unlock¶
Let the running service change KEY. Refused for credentials and protected settings.
$ keryx config unlock [OPTIONS] {key}
key: The setting. [required]
keryx auth¶
Sign in to what Keryx needs: the coding agents and Google.
$ keryx auth [OPTIONS] COMMAND [ARGS]...
keryx auth login¶
Sign in to one thing: a coding agent, Gmail (read-only), or Google for agents.
gmail is two steps: once for a link to open on any device, then again with --callback-url and the address the browser landed on.
$ keryx auth login [OPTIONS] {name}
name: claude, codex, gmail or google-workspace. [required]--headless / --browser: The agent login for a machine with no browser (default: detected).--client-file <path>: The Google OAuth client JSON you downloaded.--callback-url <str>: gmail: the address you landed on, in quotes.
keryx auth status¶
Every sign-in Keryx needs, and whether it is done. Exit 1 if one has failed.
$ keryx auth status [OPTIONS]
--json: Print JSON and nothing else.--smoke: Also run one real task on each enabled agent.
keryx memory¶
What Keryx remembers between calls.
$ keryx memory [OPTIONS] COMMAND [ARGS]...
--path: Print where the memory lives and nothing else.
keryx memory seed¶
Write a first memory from standing facts, before any call has.
For an agent: --file - --json takes the facts on stdin and prints one JSON document.
Exit 0 means the memory was written, or nothing was given to write; exit 1 means a
memory was wanted and not written (one is there without --force, or it is longer than a
call reads); exit 2 means the command line itself is wrong.
$ keryx memory seed [OPTIONS]
--file <str>: The facts, one per line; - is stdin. [required]--force: Replace a memory that already has something in it.--json: Print what every call will carry, as JSON.
keryx plugins¶
The optional voice tools (Slack, email, billing, cluster stats): on, off, set up.
$ keryx plugins [OPTIONS] COMMAND [ARGS]...
--json: Print it as one JSON document.
keryx plugins list¶
List the plugins: on or off, their two files, and why one is refused.
$ keryx plugins list [OPTIONS]
--json: Print it as one JSON document.
keryx plugins hosts¶
The hosts in ~/.ssh/config that cluster_stats could ask, and whose master is up now.
Only hosts with a ControlMaster are offered: Keryx rides a login you already have open,
and never opens its own. Nothing here reaches the network (ssh -G, ssh -O check).
$ keryx plugins hosts [OPTIONS]
--json: Print it as one JSON document.
keryx plugins install¶
Turn a plugin on, from its settings file or the values given here.
With no values, a settings file already edited by hand (and a --template draft) is
what is turned on. A secret is never taken here: keryx config set KEY --stdin, or
keryx auth login gmail. It is offered from the next call; no restart.
$ keryx plugins install [OPTIONS] [name]
name: The plugin (keryx plugins).--set <str>: KEY=VALUE for one of its settings; repeat for more.--cluster <str>: cluster_stats: ALIAS=PARTITION, the whole [clusters] table; repeat for more.--guard <str>: cluster_stats: a guard script of your own.--template: Write its settings file and a draft to edit, and leave it off untilkeryx plugins install NAME.
keryx plugins remove¶
Turn a plugin off. Its settings are set aside, so turning it on again keeps them.
$ keryx plugins remove [OPTIONS] {name}
name: The plugin. [required]-y, --yes: Do not ask first.
keryx service¶
The background service that starts Keryx at boot and brings it back if it stops.
$ keryx service [OPTIONS] COMMAND [ARGS]...
keryx service install¶
Install and start the service (systemd on Linux, launchd on macOS), and its tunnel.
Run it again after your PATH changes: the service gets this shell's, so the tasks it runs find what your terminal finds.
$ keryx service install [OPTIONS]
keryx service uninstall¶
Stop the service and its tunnel and remove them. Your settings and data stay.
$ keryx service uninstall [OPTIONS]