CLI reference

Every Tachyon command and the flags that matter.

Interactive session

Running tachyon with no arguments starts the REPL in the current directory. Passing a prompt runs it as a one-shot instead.

bash

tachyon                       # interactive REPL
tachyon "fix the failing test"  # one-shot

Flag	Effect
`--model <id>`	Override the default model, e.g. `anthropic:claude-sonnet-5`.
`--plan`	Start in plan mode, with mutating tools blocked until you approve.
`--permissions <mode>`	`ask` (default), `accept-edits`, `bypass`, `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.
`--no-color`	Disable color output.

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 Tachyon into another tool.

bash

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

Flag	Effect
`--json`	Emit a JSON summary line on stderr at exit.
`--output-schema <file>`	Emit JSON validated against a JSON Schema file.
`--max-turns <n>`	Cap agentic steps. Unlimited by default.
`--max-budget <usd>`	Hard cost ceiling in USD. Unlimited by default.
`--logs-dir <dir>`	Write `tachyon-run.json` (the full trajectory) to this directory.

Setup & diagnostics

Command	Purpose
`login [provider]`	Save an API key. `--base-url` for OpenAI-compatible endpoints.
`model [id]`	Browse the catalogue, or set the default model.
`init`	Scan the repo and generate a `CLAUDE.md` project memory file.
`doctor`	Diagnose config, keys, MCP, and sandbox availability.
`upgrade`	Install the latest build. `--check` reports only; `--force` reinstalls.
`bug`	Bundle a redacted session, config, and doctor report into a file.

Sessions & worktrees

bash

tachyon resume              # list sessions
tachyon resume <id>         # print the resume command for one
tachyon worktree list
tachyon 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

bash

tachyon mcp list | add | remove | serve | login | logout
tachyon hooks list | enable <id> | disable <id>
tachyon plugins list | trust | install | update | remove | registry
tachyon agent list | create

mcp serve exposes Tachyon's own tools as an MCP server. Pair it with --read-only to publish only the non-mutating ones — no write, edit, bash, or network:

bash

tachyon mcp serve --read-only

Scheduled runs

Headless runs on an interval or a cron expression:

bash

tachyon schedule add --name nightly-audit \
  --cron "0 9 * * *" \
  --prompt "review yesterday's commits for regressions" \
  --cwd ~/projects/api

tachyon schedule list
tachyon 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.