CLI reference — Kaeonix docs

Interactive session

Running kaeonix with no arguments starts the REPL in the current directory. Passing a prompt runs it as a one-shot instead. kx is an alias for the same binary and accepts everything below.

SESSION

kaeonix

kx "fix the failing test"

--model <id>Model for this session, e.g. avatar-1.avatar-1

--planStart in plan mode, with mutating tools blocked until you approve.on

--permissions <mode>ask, accept-edits, bypass, or auto.ask

--sandbox <mode>seatbelt, bwrap, docker, or none.auto

--resume [id]Resume a previous session; omit the id for an interactive picker.—

--worktree [name]Run in an isolated git worktree on a new branch.off

--no-colorDisable colour output.off

Headless runs

--print streams the agent's text to stdout and exits, with no TUI. This is the mode for CI, scripts, and anything piping Kaeonix into another tool.

HEADLESS

kaeonix --print "summarise the changes on this branch"

--jsonEmit machine-readable turn events on stdout.off

--output-schema <file>Emit JSON validated against a JSON Schema file.—

--max-turns <n>Cap agentic steps.unlimited

--budget <tokens>Stop the session at a token ceiling.unset

--max-budget <usd>Hard cost ceiling in USD.unlimited

--logs-dir <dir>Write kaeonix-run.json — the full trajectory — to this directory.—

Setup & diagnostics

loginSign in to a Feyncode account, or save a provider key with login <provider>.

model [id]Browse available models, or set the default.

initScan the repo and generate a CLAUDE.md project memory file.

doctorDiagnose config, credentials, MCP, and sandbox availability.

upgradeInstall the latest build. --check reports only; --force reinstalls.

bugBundle a redacted session, config, and doctor report into a file.

Sessions & worktrees

SESSIONS

kaeonix resume # list sessions

kaeonix resume <id> # print the resume command for one

kaeonix worktree list

kaeonix worktree remove <path> # --force if it has uncommitted changes

Worktrees are how you give an agent room to work without risking your checkout: it commits to its own branch, and a bad run is discarded by removing the worktree.

MCP, hooks & plugins

EXTENDING

kaeonix hooks list | enable <id> | disable <id>

kaeonix agent list | create

mcp serve exposes Kaeonix's own tools as an MCP server — see MCP servers.

Scheduled runs

Headless runs on an interval or a cron expression:

SCHEDULE

kaeonix schedule add --name nightly-audit \

--cron "0 9 * * *" \

--prompt "review yesterday's commits for regressions" \

--cwd ~/projects/api

kaeonix schedule list

kaeonix schedule run --watch

--every takes a duration (30m, 2h, 1d) as an alternative to --cron. Scheduled jobs are headless runs, so the budget caveat above applies with force — set --max-budget on anything recurring.