kx CLI Reference

kx is one binary. It is the whole agentic runtime: the local engine, the server, and every client command you use to author, run, inspect, and govern work.

This page lists every command the binary actually has. Each row is one line about what the command is for, plus the flags you are most likely to reach for. For the complete per-command usage — every flag, every subcommand — run:

kx help invoke

kx --help prints the same grouped summary you see below. kx --version prints the version.

Shared client flags

Every client command accepts these. The first four decide which server you are talking to and how you authenticate to it; --json changes the output shape.

--token and --token-file are mutually exclusive.

kx runs list --endpoint https://kx.internal:50151 --token-file ~/.kx-token --json

Exit codes

Every command uses the same four codes, so you can branch on them in a script.

Code 3 is the one worth handling deliberately. It does not mean the run failed. It means you stopped waiting. Fetch the result later with kx runs list and kx projection.

Local engine (no server)

These three drive the engine directly against a journal on disk. No server, no network, no model. They are how you see the durability guarantee for yourself — run a workflow, crash it, replay it, and compare the digest.

The flags they share:

kx run --journal /tmp/kx.db --content /tmp/kx-content --audit-log /tmp/kx-audit.jsonl
kx replay --journal /tmp/kx.db --content /tmp/kx-content
kx digest --journal /tmp/kx.db --content /tmp/kx-content

kx serve — the runtime as a server

One command starts the server, the embedded worker, and the live-event bridge. It is zero-config: leave the data paths off and the journal, content store, and catalog resolve under ~/.kortecx, are created on first run, and are reused across restarts. A startup banner prints every resolved path and endpoint.

kx serve --dev-allow-local

Set KX_DATA_DIR to move the whole zero-config layout somewhere else. The runtime is single-system by default; multi-node is on the roadmap.

Author & run

These are the commands that make something happen. Each one submits work to the server, which compiles it, derives every identity, and builds every permission from the calling party's grants. The client sends the shape of the work — never the authority to do it.

Key flags

On kx chat, --tools does not yet combine with --dataset or --image — the parser rejects the pairing rather than silently dropping one. Run them as separate turns.

kx invoke without --wait prints an async handle and returns immediately. With --wait it polls to completion and prints the committed result — the runtime called like a function.

kx invoke kx/recipes/echo --args '{"topic":"durable agents"}' --wait
kx invoke kx/recipes/echo --args '{"topic":"hello"}' --wait --out /tmp/result.bin
kx chat --message "What changed in the Q3 notes?" --dataset notes --k 6
kx agent run --goal "Summarize the open incidents and name the riskiest one."

Agents chain inside one app — a blueprint DAG, or the multi-agent patterns kx swarm composes. There is no mechanism for one app to call another app.

kx chain run "a > [b & c]" --tasks tasks.json --wait
kx chain run "[a & b] > c" --tasks tasks.json --dry-run --emit-blueprint chain.json
kx swarm "Find the risks" "Find the upside" --pattern consensus --vote judge --wait

--dry-run on chain and swarm lowers and validates the topology without submitting it, and needs no server at all.

An App is the shareable unit: a blueprint wrapped with by-reference context, tool, connection, and dataset references plus a steering config. It carries no authority — run and import re-resolve every permission against the caller's own grants.

kx app new my-agent --from-blueprint chain.json --max-turns 4 --output my-agent.app.json
kx app save my-agent.app.json --handle apps/local/my-agent
kx app run apps/local/my-agent --wait
kx app export apps/local/my-agent --bundle my-agent.appbundle
kx app import my-agent.appbundle

An exported bundle carries a source_digest lineage hint. That is a record of where the bundle came from, not a signature and not a trust decision — read an imported bundle before you run it. Connections and secrets never travel in a bundle; the importer re-registers them by name.

Inspect & observe

Everything a run did is a durable fact you can read back. These commands are all read-only unless noted, and none of them is truth-bearing input to anything — they are for looking.

An instance id is 32 hex characters; a mote id, content ref, or chain id is 64.

Key flags

kx runs list --limit 20
kx projection --instance 0123456789abcdef0123456789abcdef --at-seq 3
kx events --instance 0123456789abcdef0123456789abcdef --follow
kx events --all --follow --kind committed,failed
kx telemetry summary --instance 0123456789abcdef0123456789abcdef
kx cost 0123456789abcdef0123456789abcdef
kx alerts list --limit 50
kx health
kx info --json

A few honest limits worth stating here:

• Cost is a local spend estimate at rates you configure, with a ceiling — not a bill. It prices the run's durable turn and tool-call counters at your own KX_PRICING_PER_TURN_MICRO_USD and KX_PRICING_PER_TOOL_CALL_MICRO_USD. Input-token counts are not measured.
• Alerts means terminal failures land in an inbox instead of vanishing. There is no acknowledge or resolve lifecycle here, and nothing is sent anywhere.
• Metrics are an opt-in Prometheus /metrics endpoint, enabled with kx serve --dev-allow-local --metrics-listen <addr:port>.

Catalog, data & memory

What your agents can find, read, and remember.

Key flags

kx recipe list
kx recipe search "summarize a document" --limit 5
kx models list
kx datasets ingest notes --file ./q3-notes.md --file ./q4-plan.md
kx datasets query notes --text "what slipped in Q3" --k 5
kx memory add "The team ships on Thursdays." --kind semantic
kx memory recall --text "when do we ship" --k 3
kx context add briefing --file style=./style-guide.md --description "House style"
kx invoke kx/recipes/echo --args '{"topic":"x"}' --context briefing --wait

Tools, integrations & config

What your agents are allowed to do, and the credentials and gates around it.

Key flags

kx connections add --name notes --command ./kx-connector-notes --credential-ref NOTES_TOKEN
kx connections test --name notes
kx connections discover --name notes
kx connections fire --name notes --tool search --args '{"q":"launch"}'
kx connections doctor
kx tools list --json
kx tools score --intent "read a file from disk" --tool fs-read@1
kx secrets set --name NOTES_TOKEN --value "s3cr3t"
kx skills add --dir ./my-skill
kx new skill triage
kx new connector notes

kx connections doctor runs on your machine — it checks whether the bundled connector programs can be found — so it needs no server. Add --provider <id> to check one of them.

A secret's value is write-only: you send it once, and no command ever returns it. kx secrets list shows names and timestamps only. A connection or a trigger references a secret by name. Writing a secret (set / rm) is accepted only from a loopback caller, so run it on the same machine as the server.

Adding a skill grants nothing. A skill declares a wish for tools; at run time the server intersects that wish with your actual grants and with what can actually fire.

Approvals are the human gate: a world-changing tool call on a chain that requires approval is held, uncommitted, until an operator grants it (it then fires exactly once) or denies it (the chain fails closed). kx approvals list prints the 32-hex REQUEST_ID you pass to grant or deny.

A cron trigger's --schedule is either a plain interval in seconds or a standard five-field crontab expression, evaluated in --timezone (an IANA zone name; empty means UTC).

kx approvals list
kx approvals grant 0123456789abcdef0123456789abcdef --reason "checked the target account"
kx triggers add --name nightly --kind cron --recipe kx/recipes/echo --schedule 86400 --enabled
kx triggers add --name weekdays --kind cron --recipe kx/recipes/echo --schedule "0 9 * * 1-5" --timezone America/New_York --enabled
kx triggers test --name nightly

Help and version

kx --help
kx help chain
kx --version