JSON output#

Every --json flag prints a versioned JSON document on stdout and nothing else there; notes and errors stay on stderr. Each document carries a schema_version, fields are snake_case, token counts are integers, and money is integer micro-dollars (1,000,000 = $1.00) with an estimate_label, never a formatted string. Within a schema version Hekma only adds fields, so parse what you need and ignore the rest.

Documents at a glance#

The version belongs to the kind of content, not the command: list, show and usage share the fleet version (2), and the other families have their own.

Compatibility rule#

These documents, and the exit codes, are a stable interface:

• Within a schema_version, Hekma only adds fields. An existing field keeps its name, type and meaning.
• Fields marked optional below are left out when they have no value, rather than printed as null or 0. Treat every optional field as possibly absent.
• Removing or changing a field raises schema_version. Such a change is announced in the release notes at least one minor release ahead and happens only in a major release.

Check schema_version before you trust the rest of a document, and ignore fields you do not know.

list#

hekma agent list --json prints the whole fleet: fleet totals and one entry per agent.

{
  "schema_version": 2,
  "totals": {
    "total_input_tokens": 2400,
    "total_output_tokens": 600,
    "total_dollars": 14040,
    "dollars_partial": false,
    "unpriced_count": 0,
    "estimate_label": "estimated",
    "total_cached_tokens": 800
  },
  "instances": [
    {
      "name": "worker",
      "kind": "worker",
      "state": "running",
      "restart_count": 0,
      "restart_policy": "on-failure",
      "budget": {
        "cumulative_limit": 6000,
        "cumulative_remaining": 3000,
        "breach_action": "pause"
      },
      "usage": {
        "cumulative_input_tokens": 2400,
        "cumulative_output_tokens": 600,
        "current_run_input_tokens": 1200,
        "current_run_output_tokens": 300,
        "cumulative_dollars": 14040,
        "current_run_dollars": 7020,
        "estimate_label": "estimated",
        "cumulative_cached_tokens": 800,
        "current_run_cached_tokens": 400
      },
      "metering_source": "self-reported",
      "supervision": "detached",
      "agent_home": "/Users/you/Library/Application Support/ktesio/agents/worker"
    }
  ]
}

An empty fleet prints "instances": [] and zero totals.

totals#

Fleet entry#

Each element of instances (and the instance object of show) has these fields.

budget object#

Each limit field is present only when that budget is set; each dollar field only when a rate is also set.

Remaining values never go below 0.

usage object#

Cached tokens are a subset of input tokens. Add input and output for the total; never add cached on top. These totals equal the usage ledger exactly.

ACP fields#

Two optional fields appear only on acp agents. Every other kind leaves them out.

acp_context_usage is the agent's own report of its session context window. It is context usage, not billable usage: Hekma never adds it to the ledger or to budgets.

usage_gap appears when an acp agent's ledger holds no usage at all, and says which usage sources Hekma tried:

{
  "schema_version": 2,
  "instance": {
    "name": "coder",
    "kind": "acp",
    "state": "registered",
    "restart_count": 0,
    "restart_policy": "on-failure",
    "budget": null,
    "usage": {
      "cumulative_input_tokens": 0,
      "cumulative_output_tokens": 0,
      "current_run_input_tokens": 0,
      "current_run_output_tokens": 0,
      "cumulative_cached_tokens": 0,
      "current_run_cached_tokens": 0
    },
    "metering_source": "self-reported",
    "usage_gap": {
      "observed": "not-configured",
      "sentinel": "no-lines-seen",
      "context_usage_reported": false,
      "notice": "no billing-grade usage in the ledger — tiers attempted: observed: not-configured; sentinel: no-lines-seen; no context usage reported (ACP usage_update is context-grain, never billed)"
    },
    "agent_home": "/Users/you/Library/Application Support/ktesio/agents/coder"
  }
}

show#

hekma agent show NAME --json prints one fleet entry under instance, with the same fields and rules as a list entry.

{
  "schema_version": 2,
  "instance": {
    "name": "worker",
    "kind": "worker",
    "state": "running",
    "restart_count": 0,
    "restart_policy": "on-failure",
    "budget": {
      "cumulative_limit": 6000,
      "cumulative_remaining": 3000,
      "breach_action": "pause"
    },
    "usage": {
      "cumulative_input_tokens": 2400,
      "cumulative_output_tokens": 600,
      "current_run_input_tokens": 1200,
      "current_run_output_tokens": 300,
      "cumulative_dollars": 14040,
      "current_run_dollars": 7020,
      "estimate_label": "estimated",
      "cumulative_cached_tokens": 800,
      "current_run_cached_tokens": 400
    },
    "metering_source": "self-reported",
    "supervision": "detached",
    "agent_home": "/Users/you/Library/Application Support/ktesio/agents/worker"
  }
}

The capability declaration that the human show prints is not in this document.

usage#

With a name, hekma agent usage NAME --json prints the agent's usage object:

{
  "schema_version": 2,
  "instance": "worker",
  "usage": {
    "cumulative_input_tokens": 2400,
    "cumulative_output_tokens": 600,
    "current_run_input_tokens": 1200,
    "current_run_output_tokens": 300,
    "cumulative_dollars": 14040,
    "current_run_dollars": 7020,
    "estimate_label": "estimated",
    "cumulative_cached_tokens": 800,
    "current_run_cached_tokens": 400
  }
}

Note that instance is a plain string here, the agent's name, while in show it is an object.

Without a name, hekma agent usage --json prints the fleet totals, the same object list --json carries:

{
  "schema_version": 2,
  "totals": {
    "total_input_tokens": 2400,
    "total_output_tokens": 600,
    "total_dollars": 14040,
    "dollars_partial": false,
    "unpriced_count": 0,
    "estimate_label": "estimated",
    "total_cached_tokens": 800
  }
}

config get#

hekma agent config get NAME --json prints every effective config value; with a key, the entries list holds just that key.

{
  "schema_version": 1,
  "entries": [
    {
      "key": "agent.api_key",
      "value": "secret:****",
      "source": "instance",
      "unvalidated": true
    },
    {
      "key": "budget.tokens.cumulative",
      "value": "6000",
      "source": "instance",
      "unvalidated": false
    },
    {
      "key": "model",
      "value": "gpt-4o-mini",
      "source": "instance",
      "unvalidated": false
    }
  ]
}

With no config set, entries is an empty list. A key with no value is an error (exit code 2) and prints nothing on stdout.

logs#

hekma agent logs NAME --json prints newline-delimited JSON: one complete object per line, in capture order. The shape is the same with --follow, so you can process each line as it arrives. An empty log prints nothing.

{"schema_version":1,"instance":"worker","stream":"agent-out","at":"2026-10-22T19:07:20Z","text":"worker ready, model=gpt-4o-mini"}
{"schema_version":1,"instance":"worker","stream":"agent-out","at":"2026-10-22T19:07:20Z","text":"KTESIO_USAGE {\"sequence\": 0, \"input_tokens\": 1200, \"output_tokens\": 300, \"cached_tokens\": 400}"}
{"schema_version":1,"instance":"worker","stream":"engine","at":"2026-10-22T19:07:20Z","text":"engine: starting -> running"}

memory attach#

hekma agent memory attach NAME --kind KIND --json:

{
  "schema_version": 1,
  "instance": "worker",
  "kind": "filesystem",
  "guarantee": "managed_dir_byte_durable",
  "dir": "/Users/you/Library/Application Support/ktesio/agents/worker/memory",
  "declared": true
}

A native attach reads "kind": "native", "guarantee": "home_persistence_only" and "declared": false.

memory detach#

hekma agent memory detach NAME --json confirms the detach and nothing more; the folder and its files stay on disk.

{
  "schema_version": 1,
  "instance": "worker"
}

Engine events#

A program that embeds the engine can subscribe to events. Each event is one of three payloads wrapped with a kind tag; the payload carries its own schema_version (1 for all three). The CLI does not print events, but it writes the same transition and breach records, without the kind tag, as JSON Lines to logs/instance.log and logs/breaches.log in the Agent Home. Events, resync and diagnostics covers subscribing and catching up after a gap.

transition#

Sent after every lifecycle change. This one is an agent paused by a token budget:

{
  "kind": "transition",
  "schema_version": 1,
  "instance": "spender",
  "prior_state": "running",
  "new_state": "paused",
  "cause": {
    "kind": "budget-exceeded",
    "scope": "cumulative",
    "dimension": "tokens",
    "limit": 3000,
    "observed": 3600
  },
  "at": "2026-10-22T19:11:09Z"
}

New cause kinds may be added within version 1; handle unknown ones.

budget_breach#

Sent once per budget per run when a budget is crossed, whatever the breach action:

{
  "kind": "budget_breach",
  "schema_version": 1,
  "instance": "spender",
  "run_id": "run-1792696267061924000-0",
  "scope": "cumulative",
  "dimension": "tokens",
  "limit": 3000,
  "observed": 3600,
  "action": "pause",
  "metering_source": "self-reported",
  "at": "2026-10-22T19:11:09Z"
}

usage_update#

Sent each time a usage event is written to the ledger. A replayed event (same run and sequence) is not written again and sends nothing.

{
  "kind": "usage_update",
  "schema_version": 1,
  "event": {
    "instance": "spender",
    "run_id": "run-1792696267061924000-0",
    "input_tokens": 1000,
    "output_tokens": 200,
    "cached_tokens": 100,
    "metering_source": "self-reported",
    "sequence": 2,
    "occurred_at": "2026-10-22T19:11:09Z"
  }
}

This example was built from a usage row the v0.11.0 binary wrote to its ledger during the same run as the breach above; the field names and order are those of the engine's event type.

Read next#

• Logs, JSON and scripting: putting these documents to work in scripts.
• Exit codes and environment: the other half of the stable interface.
• Events, resync and diagnostics: receiving events from the engine.
• CLI reference: the commands that print these documents.