Headless (ka run)

ka run executes exactly one turn with no interface: built for scripts, CI, and piping.

ka run "summarize the build error"
echo "what does this repo do?" | ka run
ka run -c "continue: what else?"       # continue the newest strand
ka run --session 3f9c "next step"      # resume a specific session

Output formats

--print	Output
text (default)	The final answer only
ndjson	ka’s own event stream: literally the engine’s Event side, one JSON object per line
stream-json	Claude-Code-compatible event shapes, for tooling that already speaks that dialect

ka run --print ndjson "list the failing tests" |
  jq -c 'select(.type == "turn_finished") | .usage'

Structured output

Pass a JSON schema and the reply must satisfy it:

ka run --schema issue.schema.json "file the flaky test as JSON" > issue.json

Exit codes

Code	Meaning
0	ok
1	error
2	aborted
42	input rejected (e.g. a --schema validation failure)

Safety in headless mode

There is no human to ask, so asks resolve strictly: exec-tier calls that would prompt are denied (not auto-approved), and hardstops are denied outright. Pre-approve what a script needs with [[rules]] or [permissions] allow, or run with --mode free deliberately.