docs · reference
CLI reference#
This page lists every hekma command in Hekma 0.11.0 with its flags, a short example and the errors you are most likely to hit. Results go to stdout and notes and errors go to stderr, so --json output is always safe to pipe. For the reasoning behind a command, follow the links to the guides.
The hkm binary is the same program under a shorter name; every example works with either.
Commands at a glance#
| Command | What it does |
|---|---|
hekma agent register | Add an agent to the fleet from a built-in kind or an adapter.toml. |
hekma agent list | Show every agent with its state, supervision, budget and usage. |
hekma agent show | Show one agent's capabilities and runtime status. |
hekma agent usage | Show token and cost totals for one agent or the whole fleet. |
hekma agent start | Start an agent, for this command only or detached. |
hekma agent stop | Stop an agent: graceful first, then forced. |
hekma agent pause / resume | Suspend and wake a running agent. |
hekma agent send | Write a line to an agent's input (one prompt turn for ACP agents). |
hekma agent logs | Print an agent's captured output, optionally following it. |
hekma agent remove | Remove an agent from the fleet. |
hekma agent memory attach | Give an agent a memory backing. |
hekma agent memory detach | Remove an agent's memory backing (its files stay). |
hekma agent config set | Set one config key on an agent. |
hekma agent config get | Read an agent's effective config and where each value came from. |
hekma self-update | Update the hekma binary through the channel you installed it with. |
hekma serve (Unreleased: after 0.11.0) | Run a long-lived host that supervises a state directory. See Run Hekma as a service. |
Every agent command takes the agent's name as its first argument. Names use lowercase letters, digits, - and _, and start with a letter or digit; a bad name exits with code 2.
Every command opens the engine for as long as it runs and closes it when it exits. That is why commands print a line such as [hekma] NAME: adopted from a previous engine ... while a detached agent is running: the command found the agent and supervises it until the command exits. Supervision and detached runs explains what this means in practice.
hekma agent register <name> (--kind <kind> | --manifest <path>)#
hekma agent register <NAME> --kind <KIND>
hekma agent register <NAME> --manifest <DIR-OR-FILE>Registers a new agent under a name that is unique in the fleet and creates its Agent Home. Hekma validates the adapter first: an adapter with no supported capability or no metering source is rejected and nothing is written. On success it prints the Agent Home path and the agent's capability declaration for your OS.
| Argument or flag | Meaning |
|---|---|
<NAME> | The new agent's name. |
--kind <KIND> | A built-in kind: acp, hermes (deprecated) or mock. See Supported agents. |
--manifest <PATH> | A directory holding adapter.toml, or the file itself. See Adapter manifest. |
Give exactly one of --kind and --manifest.
hekma agent register worker --manifest /Users/you/agents/worker✓ Registered Agent Instance worker (worker)
/Users/you/Library/Application Support/ktesio/agents/worker
▸ Capabilities for worker (OS: macos) (1 row)
Capability Support (curren…
──────────────────────────────
pause guaranteedHekma copies the manifest's launch command at registration. If you edit adapter.toml later, remove and register the agent again for the change to apply. Hekma also reads the file again at every start for its config mappings, from the path you gave, so register with an absolute path.
| Error | Exit code |
|---|---|
| The name is taken, or is not a valid name | 2 |
Unknown --kind | 2 |
No adapter.toml at the --manifest path | 3 |
| The manifest is invalid, unreadable, or targets another contract major version | 1 |
| The adapter declares no capabilities or no metering source | 1 |
Guides: Run an ACP agent, Bring your own agent.
hekma agent list [--json]#
hekma agent list [--json]Shows every agent in the fleet as a table, followed by a fleet total line.
| Flag | Meaning |
|---|---|
--json | Print the fleet as one JSON document instead. See JSON output. |
$ hekma agent list
▸ Fleet (1 row)
Name Kind State Supervision Restarts Budget (tok, est. $) Usage (tok, est. $) Agent Home
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
worker worker running detached 0 cum 3000/6000 tok (pause) in 2400 / out 600 / cac… /Users/you/Libr…
Fleet total: in 2400 / out 600 / cached 800 · ≈ $0.01 (estimated)| Column | What it shows |
|---|---|
| State | The agent's lifecycle state. |
| Supervision | detached, session, or — when no live process is recorded. See supervision. |
| Restarts | Consecutive restarts made by the restart policy. |
| Budget | Remaining over limit for each budget scope, then the breach action, for example cum 3000/6000 tok (pause). — means no budget. |
| Usage | Cumulative input, output and cached tokens from the usage ledger, plus an estimated cost when a rate is set. |
Cells are cut to fit the terminal; widen it (or set COLUMNS), or use --json. With an empty fleet the command prints a hint to register an agent and exits 0. The metering source is not a column; read it from show, usage or --json.
hekma agent show <name> [--json]#
hekma agent show <NAME> [--json]Shows one agent: its capability declaration for your OS, then its runtime status (state, restart policy and count, budget, usage, estimated cost, metering source and supervision). A failed agent also gets a Failed cause line, and an ACP agent gets an ACP context usage row.
| Flag | Meaning |
|---|---|
--json | Print the status as one JSON document. See JSON output. |
$ hekma agent show worker
▸ Capabilities for worker (OS: macos) (1 row)
Capability Support (curren…
──────────────────────────────
pause guaranteed
▸ Runtime status for worker (8 rows)
Field Value
──────────────────────────────────────────────────────────────────
State failed
Restart policy on-failure
Restart count 0
Budget cum 4500/6000 tok (pause)
Usage (tokens) in 1200 / out 300 / cached 400 · $0.01 (estimat…
Cost (estimated) $0.01 (estimated)
Metering source self-reported
Supervision —
• Failed cause: orphan not found on engine restart (process pid 65596 is gone or was reused); last known: no prior cause recordedThat failed cause is what you see after a plain start whose command has exited: the agent stopped with the command, and the next command recorded it as failed. See start.
| Error | Exit code |
|---|---|
| No agent with that name | 3 |
hekma agent usage [<name>] [--json]#
hekma agent usage [NAME] [--json]With a name, shows that agent's tokens over its whole life (cumulative) and for its current run, the estimated cost of each, and its metering source. Without a name, shows the fleet total. The numbers are the ones list and show print, read from the same ledger.
| Argument or flag | Meaning |
|---|---|
[NAME] | The agent to report on. Omit it for the fleet total. |
--json | Print one JSON document. See JSON output. |
$ hekma agent usage worker
▸ Usage for worker (5 rows)
Field Value
──────────────────────────────────────────────────
Cumulative tokens in 2400 / out 600 / cached 800
Cumulative cost $0.01 (estimated)
Current-run tokens in 1200 / out 300 / cached 400
Current-run cost $0.01 (estimated)
Metering source self-reportedCached tokens are part of the input count, never added on top. Costs appear only when a rate is set and are always labelled estimates; with no rate the cost reads —. When some agents have usage but no rate, the fleet cost is a lower bound and says how many agents it left out.
| Error | Exit code |
|---|---|
| No agent with that name | 3 |
Guides: Meter token usage, Budgets and cost.
hekma agent start <name> [--detach]#
hekma agent start <NAME> [--detach]Starts a registered, stopped or failed agent and prints its new state, running. Before launching, Hekma resolves the agent's config and secrets and writes the effective config (secrets masked) to effective-config.json in the Agent Home.
| Flag | Meaning |
|---|---|
--detach | Keep the agent running after this command exits. |
Without --detach, the agent belongs to this command, and the command exits as soon as the agent is up. Hekma says so:
$ hekma agent start worker
✓ Started Agent Instance worker
running
• note: the started process is supervised only for this engine session and stops when this command exits; start it with --detach to keep it running across commands.So a plain start from a terminal is useful only to check that an agent launches: the agent stops a moment later, and the next command marks it failed with "orphan not found on engine restart". To keep an agent running, add --detach:
$ hekma agent start worker --detach
✓ Started Agent Instance worker
running
• note: detached: the agent keeps running after this command exits, and the next `hekma` command re-adopts it. Until then it is NOT supervised: no crash detection, no budget enforcement, and no usage/event delivery happen between commands (supervision is command-scoped).A detached agent is supervised only while some hekma command runs, and usage it reports between commands is not counted later. Keep hekma agent logs NAME --follow running to supervise it continuously; Supervision and detached runs shows the pattern. A detached agent also starts with stdin closed, so an agent that reads stdin exits at once and the start ends failed.
| Error | Exit code |
|---|---|
| No agent with that name | 3 |
| The agent is already running or paused | 4 |
| A memory attach or detach in another terminal raced this start (nothing launched; retry) | 4 |
--detach on an engine-observed agent (nothing changed) | 5 |
The launch failed and the agent is now failed. This includes the mock kind, which has no launch command, and an acp agent without acp.command | 1 |
A secret:NAME value could not be resolved (nothing changed) | 1 |
hekma agent stop <name> [--timeout <secs>]#
hekma agent stop <NAME> [--timeout <SECS>]Stops a running or paused agent. Hekma asks the process to exit (SIGTERM to its process group on Unix), waits up to the timeout, then kills the whole group. An ACP agent with a prompt turn in progress gets session/cancel first.
| Flag | Meaning |
|---|---|
--timeout <SECS> | Seconds to wait before the forced kill. Default 30; 0 kills at once. |
$ hekma agent stop worker --timeout 3
✓ Stopped Agent Instance worker
stopped| Error | Exit code |
|---|---|
| No agent with that name | 3 |
| The agent is not running or paused | 4 |
The process could not be confirmed dead after the forced kill (it stays stopping; run stop again) | 4 |
hekma agent pause <name> / hekma agent resume <name>#
hekma agent pause <NAME>
hekma agent resume <NAME>pause suspends a running agent and resume wakes a paused one. The result depends on the agent's declared pause capability on your OS: guaranteed really suspends the process (SIGSTOP and SIGCONT on Unix), best-effort records the pause with a note that it is cooperative, and unsupported fails before anything changes.
$ hekma agent pause worker
✓ Paused Agent Instance worker
pausedAn operator pause lasts only while some command holds the agent. On a detached agent, Hekma resumes the process when the pause command exits, and says so:
[hekma] worker: paused detached child resumed at engine release (SIGCONT before the handle was released) — a detached instance is only paused while an engine session holds it; the row is now 'running'A pause caused by a budget breach is different: it holds between commands until you resume or stop the agent. See Budgets and cost.
| Error | Exit code |
|---|---|
| No agent with that name | 3 |
pause on an agent that is not running, or resume on one that is not paused | 4 |
The agent declares pause unsupported on this OS | 5 |
resume of a paused agent whose declaration now reads unsupported (recover with stop, then start) | 5 |
hekma agent send <name> <text>#
hekma agent send <NAME> <TEXT>Writes <TEXT> to a running agent's stdin, adding a trailing newline if there is none. For an acp agent, the text becomes one prompt turn: the command returns at once and the reply streams into hekma agent logs. <TEXT> may start with - and is still sent as text; for that reason send has no --help flag.
From the CLI alone, send has no usable target in 0.11.0. send needs the stdin pipe that the starting process holds. An agent started without --detach stops when its start command exits, and a detached agent starts with stdin closed, so a later send fails:
$ hekma agent send sleeper "hello"
✗ Agent Instance 'sleeper' cannot receive input right now: no live stdin pipe is held for this instance in this engine session (an adopted instance has no recoverable pipe; ...). Durable cross-invocation interaction needs a persistent engine session (planned for a future release); within a single `hekma` process/embedding session this works.Sending works from a program that embeds the engine and keeps it open from start to send. The long-running hekma serve host (Unreleased: after 0.11.0) has no send route either.
| Error | Exit code |
|---|---|
| No agent with that name | 3 |
| The agent is not running | 4 |
An acp agent already has a prompt turn in progress | 4 |
The agent declares interaction unsupported on this OS | 5 |
| This command holds no input pipe for the agent (the case above) | 5 |
| The agent did not read its input in time; its input stays closed until it is restarted | 6 |
hekma agent logs <name> [--follow] [--json]#
hekma agent logs <NAME> [-f | --follow] [--json]Prints the agent's captured output as <time> [<stream>] <text>, one line per entry, in the order it was captured. The stream is agent-out (the agent's stdout), agent-err (its stderr) or engine (a line Hekma adds at each state change). Logs work for every agent, whatever capabilities it declares.
| Flag | Meaning |
|---|---|
-f, --follow | After printing what is captured, keep printing new lines until the agent stops, pauses or fails. |
--json | Print each line as one JSON object (NDJSON). See JSON output. |
$ hekma agent logs worker
2026-10-22T19:07:20Z [agent-out] worker ready, model=gpt-4o-mini
2026-10-22T19:07:20Z [agent-out] KTESIO_USAGE {"sequence": 0, "input_tokens": 1200, "output_tokens": 300, "cached_tokens": 400}
2026-10-22T19:07:20Z [engine] engine: starting -> running--follow keeps running until the agent leaves running or you press Ctrl+C, and it keeps the engine open the whole time: while it runs, a detached agent's usage is metered and its budgets are enforced. It ends with a note when the agent leaves running, for example note: Agent Instance 'worker' is paused; no further output until it is resumed. For a detached agent, new lines come straight from the agent's raw log, after a note that their timestamps are when the command read them. Lines written before the follow started are not replayed; see Follow live output.
Hekma keeps up to 10 MB of attributed output per file plus the two previous files. The one-shot form prints whatever is retained and never fails because of rotation. Ending the output early (for example with | head) exits cleanly with code 0.
| Error | Exit code |
|---|---|
| No agent with that name | 3 |
Guide: Logs, JSON and scripting.
hekma agent remove <name> [--delete | --retain] [--force]#
hekma agent remove <NAME> [--delete | --retain] [--force]Removes an agent from the fleet. By default its Agent Home stays on disk.
| Flag | Meaning |
|---|---|
--retain | Keep the Agent Home (the default). |
--delete | Delete the Agent Home too, including its logs and any memory/ folder. |
--force | Remove even if the agent is running; its process is stopped. |
$ hekma agent remove worker
✓ Agent Instance worker removed (Agent Home retained)| Error | Exit code |
|---|---|
--delete together with --retain | 2 |
| No agent with that name | 3 |
The agent is running and --force was not given | 4 |
| The Agent Home could not be deleted (the agent is removed; delete the folder yourself) | 1 |
hekma agent memory attach <name> --kind <kind>#
hekma agent memory attach <NAME> --kind <filesystem|native> [--json]Attaches a memory backing. filesystem creates a memory/ folder in the Agent Home and passes its path to the agent at every start; native records that the agent manages its own memory and creates nothing. The agent must be registered, stopped or failed.
| Flag | Meaning |
|---|---|
--kind <KIND> | filesystem or native. |
--json | Print one JSON document. See JSON output. |
The confirmation ends with the folder path alone on the last line, so a script can read it with tail -n 1:
$ hekma agent memory attach worker --kind filesystem
✓ Attached filesystem Memory Backing to Agent Instance worker
Ktesio guarantees the managed directory: it exists, survives restarts byte-identically, and travels with the Agent Home.
/Users/you/Library/Application Support/ktesio/agents/worker/memoryAttaching the same kind again succeeds and changes nothing.
| Error | Exit code |
|---|---|
Unknown --kind | 2 |
| No agent with that name | 3 |
| The agent is running, paused, starting or stopping | 4 |
| A different kind is already attached (detach it first) | 4 |
| The attachment was saved but the folder could not be created (the next start creates it) | 1 |
Guide: Config, secrets and memory.
Moving an Agent Home to another machine#
This moved to Config, secrets and memory.
hekma agent memory detach <name>#
hekma agent memory detach <NAME> [--json]Removes the memory backing record. The memory/ folder and its files stay on disk, and attaching filesystem again later picks them up. The same state rule applies as for attach.
| Flag | Meaning |
|---|---|
--json | Print one JSON document. See JSON output. |
$ hekma agent memory detach worker
✓ Detached the Memory Backing from Agent Instance worker (the managed directory and its contents remain on disk)| Error | Exit code |
|---|---|
| No agent with that name | 3 |
| The agent is running, paused, starting or stopping | 4 |
hekma agent config set <name> <key> <value>#
hekma agent config set <NAME> <KEY> <VALUE>Sets one key on the agent's own config layer. Hekma checks the key and, for budget and price keys, the value before writing anything. The value is stored as written: a secret:NAME reference stays a reference and is resolved only at start. The file is replaced in one step, so a crash never leaves it half-written.
| Argument | Meaning |
|---|---|
<KEY> | A key from Config keys, or any key under agent. |
<VALUE> | The value. A value that starts with - is taken literally; -- before it is optional. |
$ hekma agent config set worker budget.tokens.cumulative 6000
✓ Set budget.tokens.cumulative = 6000 on Agent Instance worker (instance layer)Changes apply at the agent's next start. Budget, breach action and rate keys are the exception: Hekma reads them again at every usage event, so they apply at once to a supervised agent. If you put a secret: value on a key the adapter passes as a command-line flag, the write succeeds with a warning, because other local users can read a process's arguments.
| Error | Exit code |
|---|---|
Unknown key outside agent. (the error suggests the nearest key) | 2 |
| No agent with that name | 3 |
| Invalid value for a budget, breach action or price key (nothing changed) | 1 |
Guide: Config, secrets and memory.
hekma agent config get <name> [<key>] [--json] [--reveal]#
hekma agent config get <NAME> [KEY] [--json] [--reveal]Prints the agent's effective config: each key, its value, whether Hekma validated the key, and the config layer the value came from. With a key, prints only that value.
| Argument or flag | Meaning |
|---|---|
[KEY] | Print only this key's value. |
--json | Print one JSON document. See JSON output. |
--reveal | Show secret: values in clear text. Hekma resolves them again now, from the environment and then secrets.toml. |
$ hekma agent config get worker
▸ Effective config for worker (4 rows)
Key Value Validated Source
─────────────────────────────────────────────────────────────────
agent.api_key secret:**** unvalidated instance
budget.tokens.cumulative 6000 validated instance
cost.rate.input 3.00 validated instance
model gpt-4o-mini validated instance| Error | Exit code |
|---|---|
The key has no value (for a prefix such as budget, the error lists the keys under it) | 2 |
| No agent with that name | 3 |
--reveal could not resolve a secret, or secrets.toml is readable by other users | 1 |
Config keys#
The full list of keys, with types, defaults and validation, is on Config keys. How budgets behave is on Budgets and cost.
Exit codes#
Every command exits 0 on success, or 1 to 6 by error class: 1 general, 2 usage, 3 not found, 4 invalid state, 5 unsupported, 6 timed out. The full table, with every condition, is on Exit codes and environment.
Environment variables#
The variables Hekma reads, such as HEKMA_STATE_DIR and HEKMA_NO_UPDATE_CHECK, and the ones it sets for agents are listed on Exit codes and environment.
Update checks#
When you run any command other than self-update, Hekma checks GitHub for a newer release at most once an hour and, if there is one, prints a one-line note on stderr suggesting hekma self-update. JSON on stdout is unaffected. Set HEKMA_NO_UPDATE_CHECK=1 to turn the check off; it is also off when CI is set. Details are on Exit codes and environment.
hekma self-update#
hekma self-updateUpdates the hekma binary through the channel you installed it with: brew upgrade for Homebrew, cargo install --force for Cargo, and a verified download of the latest GitHub release archive for a manual install. Agents are separate programs, so an update does not touch them: detached agents keep running, and the next hekma command, now the new version, adopts them.
| Error | Exit code |
|---|---|
| The update failed | 1 |
Guide: Install.
Read next#
- Config keys: every key
config setaccepts. - JSON output: the documents
--jsonprints. - Exit codes and environment: codes for scripts and the variables Hekma reads.
- Supervision and detached runs: how to keep agents running and governed.