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#

CommandWhat it does
hekma agent registerAdd an agent to the fleet from a built-in kind or an adapter.toml.
hekma agent listShow every agent with its state, supervision, budget and usage.
hekma agent showShow one agent's capabilities and runtime status.
hekma agent usageShow token and cost totals for one agent or the whole fleet.
hekma agent startStart an agent, for this command only or detached.
hekma agent stopStop an agent: graceful first, then forced.
hekma agent pause / resumeSuspend and wake a running agent.
hekma agent sendWrite a line to an agent's input (one prompt turn for ACP agents).
hekma agent logsPrint an agent's captured output, optionally following it.
hekma agent removeRemove an agent from the fleet.
hekma agent memory attachGive an agent a memory backing.
hekma agent memory detachRemove an agent's memory backing (its files stay).
hekma agent config setSet one config key on an agent.
hekma agent config getRead an agent's effective config and where each value came from.
hekma self-updateUpdate 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 flagMeaning
<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         guaranteed

Hekma 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.

ErrorExit code
The name is taken, or is not a valid name2
Unknown --kind2
No adapter.toml at the --manifest path3
The manifest is invalid, unreadable, or targets another contract major version1
The adapter declares no capabilities or no metering source1

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.

FlagMeaning
--jsonPrint 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)
ColumnWhat it shows
StateThe agent's lifecycle state.
Supervisiondetached, session, or — when no live process is recorded. See supervision.
RestartsConsecutive restarts made by the restart policy.
BudgetRemaining over limit for each budget scope, then the breach action, for example cum 3000/6000 tok (pause). — means no budget.
UsageCumulative 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.

FlagMeaning
--jsonPrint 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 recorded

That 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.

ErrorExit code
No agent with that name3

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 flagMeaning
[NAME]The agent to report on. Omit it for the fleet total.
--jsonPrint 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-reported

Cached 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.

ErrorExit code
No agent with that name3

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.

FlagMeaning
--detachKeep 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.

ErrorExit code
No agent with that name3
The agent is already running or paused4
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.command1
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.

FlagMeaning
--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
ErrorExit code
No agent with that name3
The agent is not running or paused4
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
paused

An 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.

ErrorExit code
No agent with that name3
pause on an agent that is not running, or resume on one that is not paused4
The agent declares pause unsupported on this OS5
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.

ErrorExit code
No agent with that name3
The agent is not running4
An acp agent already has a prompt turn in progress4
The agent declares interaction unsupported on this OS5
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 restarted6

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.

FlagMeaning
-f, --followAfter printing what is captured, keep printing new lines until the agent stops, pauses or fails.
--jsonPrint 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.

ErrorExit code
No agent with that name3

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.

FlagMeaning
--retainKeep the Agent Home (the default).
--deleteDelete the Agent Home too, including its logs and any memory/ folder.
--forceRemove even if the agent is running; its process is stopped.
$ hekma agent remove worker
✓ Agent Instance worker removed (Agent Home retained)
ErrorExit code
--delete together with --retain2
No agent with that name3
The agent is running and --force was not given4
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.

FlagMeaning
--kind <KIND>filesystem or native.
--jsonPrint 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/memory

Attaching the same kind again succeeds and changes nothing.

ErrorExit code
Unknown --kind2
No agent with that name3
The agent is running, paused, starting or stopping4
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.

FlagMeaning
--jsonPrint 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)
ErrorExit code
No agent with that name3
The agent is running, paused, starting or stopping4

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.

ArgumentMeaning
<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.

ErrorExit code
Unknown key outside agent. (the error suggests the nearest key)2
No agent with that name3
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 flagMeaning
[KEY]Print only this key's value.
--jsonPrint one JSON document. See JSON output.
--revealShow 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
ErrorExit code
The key has no value (for a prefix such as budget, the error lists the keys under it)2
No agent with that name3
--reveal could not resolve a secret, or secrets.toml is readable by other users1

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-update

Updates 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.

ErrorExit code
The update failed1

Guide: Install.