CLI reference

tomo [command] [flags]

tomo is one binary with a small command tree. tomo chat talks to the model from the terminal, tomo serve runs the daemon behind your chat apps, tomo onboard writes a starter config, tomo doctor checks it is ready, tomo watch shows what the agent is doing, and the rest manage sessions, plans, scheduled jobs, and skills. Run tomo <command> --help for the canonical, up-to-date flag list rendered from the binary itself.

Global

tomo
tomo --version
tomo <command> --config <path>

The root command does nothing on its own; it prints help and holds the flags every subcommand shares.

Flag	Default	Meaning
--config	~/.tomo/config.yaml	Config file to read. This is a persistent flag, so it works on every subcommand.
-p, --prompt		Run one prompt non-interactively and exit.
--version		Print the build version and exit.

Every command that touches state reads the config named by --config, or the default location when the flag is empty. A missing config is an error that names the fix: run tomo onboard.

tomo -p "<prompt>" runs a single prompt against the same build as chat, then exits, for scripts and pipelines. The whole prompt is one turn, newlines and all, so a multi-line prompt is not fragmented across turns. A job that needs more than one step is planned in that same turn: the model calls the plan tool to lay out the steps and works through them without leaving the turn, which is cheaper than running a step per fresh context. For a job you want run as isolated steps with their own budgets, use plan run instead.

chat

tomo chat [flags]

A streaming REPL against the configured model, rendered in your terminal. Assistant text streams as it arrives, and each tool call prints a [name] input line when it starts and a [name done] or [name failed] line when it finishes. Takes no positional arguments.

Flag	Default	Meaning
-m, --model	config default_model	Provider/model to run this session, like anthropic/claude-fable-5.
-s, --session		Named session to continue in the ledger. Without it the conversation is in-memory only and gone when you exit.

With --session the conversation persists to the ledger under the terminal channel and picks up where it left off, replaying the stored history on start.

Inside the REPL two control words are handled locally, before any model call:

• /new clears the working context and starts a fresh conversation. The ledger keeps the past; only the in-memory history is dropped.
• /exit leaves the REPL. An end-of-input (Ctrl-D) does the same.

An empty line is ignored.

serve

tomo serve [flags]

Runs tomo as a daemon: the local web chat plus every channel you have configured. The web chat is always on; Telegram, Discord, Slack, and iMessage start only when their config is present. Takes no positional arguments.

Flag	Default	Meaning
--addr	127.0.0.1:8765	Listen address for the web chat. Loopback by default, so it is not reachable off the machine.
-m, --model	config default_model	Provider/model for the default worker.

Before it opens anything it runs the same checks as tomo doctor and refuses to start if one fails, printing the named fix rather than half-starting and failing on the first turn. On start it prints the serving address, each active channel, any extra workers, whether voice is wired in, and whether the heartbeat is running. If --addr is not a loopback address it prints a warning, because the web chat is then reachable from other hosts; the address is resolved and range-checked, so a trailing-dot or decimal spelling of loopback does not slip past it. It also runs the scheduler, so cron jobs fire and post their results while serve is up.

Send /session <name> from any chat to bind that conversation to a shared, named session in the ledger; this is handled by the router, covered under chat commands below.

Chat commands in a channel

Inside a served conversation (any channel, including the web chat) the router answers one control message itself, before the model is called:

• /session on its own reports the current session key for this chat.
• /session <name> links this chat to the named session. Bind two channels to the same name to carry one conversation between them.

plan

tomo plan <subcommand>

A plan is tomo working a job that is more than one turn: research a few libraries and compare them, clean a directory and run the tests. plan run turns the job into a small graph of steps, runs the independent ones at once through the same gate, checks each against a grounded postcondition, and records the run in the ledger so you can look back at it.

Most jobs do not need this. A one-shot tomo -p "<job>" plans in context: the model calls the plan tool to lay out the steps and works through them in one turn. Reach for tomo plan run when you want the steps run as isolated workers with their own budgets and postconditions.

plan run

tomo plan run <job>

Plans the job and runs it to completion, streaming each step as it goes. The one positional argument is the job to do. If the job reads like a single turn it says so and runs it as a job anyway.

Flag	Default	Meaning
-m, --model	config default_model	Provider/model to plan and run with.
--concurrency	3	How many independent steps may run at once.
--steps	40	Step budget, a runaway backstop. 0 for unbounded.

plan list

tomo plan list [--status <status>]

Lists the plans in the ledger: id, status, step progress, and a truncated goal. Prints a hint when there are none. Takes no positional arguments.

Flag	Default	Meaning
--status		Filter by status, like running, done, or failed.

plan show

tomo plan show <id> [--follow]

Shows a plan's steps and their status. The one positional argument is the plan id from plan list.

Flag	Default	Meaning
--follow		Redraw live as the steps advance, for a plan that is still running.

onboard

tomo onboard

Sets up ~/.tomo and writes a starter config.yaml. It creates the data dir plus the memory and skills subdirs, then writes the annotated config template if none exists yet. If a config is already there it says so and leaves it alone. Takes no positional arguments; it honors the global --config to choose where the file lands. After writing the file it ends at the next real action, not a wall of YAML: if the default provider's key is already in the environment it points you at tomo doctor and tomo chat; if not, it prints the exact export line to set first.

doctor

tomo doctor

Checks tomo's startup preconditions and prints one line per check with a named fix for anything wrong, then exits non-zero if any check failed. It confirms the config loads, the default provider resolves and has a key, the data dir is writable, and every configured channel has a driver. tomo serve runs the same checks on boot, so doctor tells you ahead of time what would stop it from starting. Takes no positional arguments; honors the global --config.

watch

tomo watch [flags]

A live, read-only view of the audit log: each tool call, its class, the gate's decision (allow, ask, deny), whether it ran, the session's taint state, and the reason. It is read-only by construction; no control action travels over it, so there is nothing for it to be tricked into doing. Credentials never reach the audit log in the first place, so nothing here has to be redacted after the fact. Takes no positional arguments.

Flag	Default	Meaning
-f, --follow	true	Keep watching for new entries. Pass --follow=false to print what is there and exit.

sessions

tomo sessions

Lists the conversations in the ledger as a table of name, channel, message count, and last-updated time. Prints a hint when there are none yet. Takes no positional arguments.

traces

tomo traces
tomo traces list [flags]
tomo traces summary [flags]
tomo traces export RUN_ID [-o FILE] [--format sts|native]
tomo traces export-all OUTPUT_DIR [flags]

Inspects the normalized model-call ledger. The default command prints aggregate run, call, failure, detailed token, priced cost, duration, and deduplicated-object totals. list filters individual runs by exact model or provider, task identifier or label, run date, and starting time. export writes Hugging Face Session Trace Simple Format JSONL by default, ready for a dataset or Storage Bucket. --format native writes tomo's lossless resolved JSON document. export-all materializes every matching run under year/month/day/provider/model/task/run.jsonl, ready to upload as one dataset.

The ledger stores repeated prompt components once by content hash, so a multi-round conversation does not copy its entire earlier transcript into every trace entry.

Flag	Commands	Meaning
--model	list, summary	Exact model identifier.
--provider	list, summary	Exact configured provider name.
--task	list, summary	Exact task identifier or task-label substring.
--date	list, summary	Run date in YYYY-MM-DD form.
--since	list, summary	Inclusive RFC3339 starting time.
--json	list, summary	Machine-readable output.
--limit	list	Maximum runs, default 50.
-o, --output	export	Write the resolved run to a file instead of standard output.
--format	export	sts for upload-ready Hugging Face trace JSONL, or native for lossless resolved JSON. Default sts.
--model, --provider, --task, --date, --since	export-all	Materialize only matching runs.

channel

tomo channel <subcommand>

Inspects and extends the set of channels tomo serve can open. Each channel is a driver registered by name, so the core dispatches to it the way the standard library dispatches a database driver. See the channels guide.

channel list

tomo channel list

Lists the channel drivers built into this binary, one per line. Takes no positional arguments.

channel scaffold

tomo channel scaffold <name>

Generates a starter adapter package for a new channel at pkg/channel/<name>/<name>.go: the registration, the driver struct, the allow-list field, and the interface methods stubbed, with a Run that reports it is not implemented yet. The name must start with a lowercase letter and hold only lowercase letters, digits, and underscores. It refuses to overwrite an existing driver or directory. On success it prints the two edits left to wire it in: fill in Run, and add the side-effect import next to the other channel drivers. The output is plain Go that compiles as generated.

cron

tomo cron <subcommand>

Manages the jobs tomo runs unattended. A job is a prompt on a schedule, aimed at a channel and chat; when serve is running it fires the prompt and posts the result there. See the scheduling guide for the full picture.

cron add

tomo cron add <schedule> <prompt> --channel <name> --chat <id>

Adds a scheduled prompt. Both positional arguments are required: the schedule and the prompt. The schedule is validated up front, and both --channel and --chat are required. On success it prints the new job id.

Flag	Default	Meaning
--channel		Channel to post results to: telegram, discord, slack, or imessage. Required.
--chat		Chat id within that channel. Required.

The schedule accepts three forms:

• Standard five-field cron (minute hour day-of-month month day-of-week), evaluated in the local time zone, for example 0 8 * * *.
• A descriptor macro: @hourly, @daily, @midnight, @weekly, @monthly, @yearly, or @annually.
• @every <duration>, a fixed interval after the previous run, for example @every 30m. The duration is a Go duration string and must be positive.

cron list

tomo cron list

Lists the scheduled jobs as a table: id, schedule, channel, chat, whether it is on, last run, and a truncated prompt. Prints no jobs when there are none. Takes no positional arguments.

cron rm

tomo cron rm <id>

Removes a scheduled job by numeric id. Errors if the id is not a number or no such job exists.

cron log

tomo cron log [--limit <n>]

Shows recent job runs as a table: job id, when it started, whether it succeeded, and a truncated one-line output. Takes no positional arguments.

Flag	Default	Meaning
--limit	20	How many runs to show.

skills

tomo skills <subcommand>

Manages the markdown skills tomo can follow. A skill is a folder under the data dir holding a SKILL.md with a name, a description, and a permission manifest. Nothing installs skills but you; there is no remote hub. The curator may draft one from a workflow it sees you repeat, and those wait under drafts until you install them. See the memory and skills guide.

skills list

tomo skills list

Lists installed skills and their state as a table: name, whether it is on, its permission manifest as an rnwx string, and description. A broken skill shows the parse error in place. Prints no skills installed when empty. Takes no positional arguments.

skills lint

tomo skills lint

Scans installed skills for hidden instructions and capabilities they use but did not declare. Prints one line per finding as skill: level: message, and exits non-zero when any are found. Prints no problems found and exits zero when clean. Takes no positional arguments.

skills enable

tomo skills enable <name>

Enables a skill so it rides in the prompt.

skills disable

tomo skills disable <name>

Disables a skill without removing it.

skills drafts

tomo skills drafts

Lists the skills the curator has proposed for you to review, as a table of name, permissions, and description. Drafts live apart from installed skills and never ride in the prompt until you install one. Prints no drafts waiting when empty. Takes no positional arguments.

skills install

tomo skills install <name>

Promotes a drafted skill into your installed skills so it rides in the prompt. This is the explicit step: nothing a reflection drafts takes effect until you install it. Lint it first if you want a closer look.

skills discard

tomo skills discard <name>

Throws away a drafted skill you do not want.

mcp

tomo mcp [flags]

Serves tomo's own tools over the Model Context Protocol on stdio, so an MCP client like Claude Code can reach them. The client gains a tomo_chat tool that runs a full tomo turn, the memory recall and store tools, and one to schedule later work. Only JSON-RPC travels on stdout, so nothing else prints there. Actions gated to ask are declined, since a server has no one to prompt. Takes no positional arguments. See the MCP guide.

Flag	Default	Meaning
-m, --model	config default_model	Provider/model for the chat tool.

version

tomo version

Prints the version, commit, build date, Go toolchain, and target platform, the same block a Go tool shows. A release binary carries these stamped in by goreleaser. A binary from go install github.com/tamnd/tomo/cmd/tomo@<commit> has no stamp, so this falls back to the build info the Go toolchain embeds in every binary and recovers the commit and date from the module's pseudo-version. tomo --version prints the same information as one line. Takes no positional arguments and no flags.