CLI commands

The table

Everyday

Account

See Account & sign-in. None of it is required to use Titah.

Configuration

Frequently used options

titah --help prints the same list, and titah --version the version alone.

titah run versus titah

titah run executes the core in process, not over HTTP. It uses the exact same agent loop and the same storage, just skipping the network layer.

titah run "how many .ts files are in src/? Use glob."
titah run -a build-auto "fix the failing tests"
titah run -m anthropic/claude-sonnet-5 -s 4f2a "continue where we left off"

titah with no arguments spawns a server on a random port and attaches the TUI to it. It feels like one process, but the architecture is client/server throughout — which is why titah attach http://host:4096 works with no extra code.

titah serve

titah serve --port 4096

Exposes the full core over HTTP + SSE. See HTTP API for every route.

!!! warning “Bare serve auto-denies” With no client connected, any tool that would raise a permission dialog is auto-denied and logged. Blocking forever would freeze the agent in CI; auto-allowing would turn headless mode into a silent security hole. For automation use --auto or an explicit permission.allowlist.

titah sessions

titah sessions list              # this folder, newest first
titah sessions list --all        # every project, with each session's path
titah sessions prune --older-than 30d

Sessions belong to the folder you opened Titah in. A conversation is nearly always tied to the code being worked on, and a list mixing every project on the machine buries the one you actually want.

The match is on the exact directory, so ~/proj and ~/proj/src are separate projects. Paths are normalised first, so a trailing slash or a relative path finds the same sessions.

titah undo

titah undo             # the most recently updated top-level session here
titah undo -s <id>     # a specific session

A bare titah undo never picks a child (sub-agent) session automatically. Read Permissions & undo before relying on it in a /tim turn — there is a real sharp edge there.

titah doctor

titah doctor
titah doctor --probe

Reports:

• Node version, platform, install path
• Config file locations and the merged result, redacted
• Which credentials resolved, and from which source
• Which external agent CLIs were detected, and the exact command missing for those that were not
• Skills found per namespace, plus conflicts, empty paths, and unresolved ids
• Extensions: per configured extension, whether its manifest reads and its engines.titah matches this build’s extension API — deliberately without importing anything, the same rule as the MCP section, and the limit is printed rather than hidden: a factory that throws only when the module runs still belongs to titah extension list
• Every model with no declared contextWindow
• Every model where the reserved compaction cap is biting, and the value actually in effect
• Whether websearch is on the ddg backend, which scrapes HTML and can break without warning
• Which sandbox state bash is in — enabled and available, enabled with no sandbox on this platform (so bash is refused), or off
• The account this machine is signed in as, if any
• Whether this folder is reported to your dashboard, which of the four switches is in effect, and when it last sent

--probe additionally tests network reachability per provider.

titah stats

titah stats                 # this folder, all time
titah stats --since 7d      # the last week
titah stats --all           # every project on the machine

231 turns across 74 sessions · all time · every project

  by model
    9router/ant     174 turns   29.7M in   241.2k out    12.34

  by day
    2026-08-17       72 turns   23.3M in   142.1k out     9.81

  total  30,283,249 in / 296,374 out  ·  12.34

Cost appears only for models that declare a price. Titah ships no price table: prices change by region and contract, and a stale table produces numbers that look official and are wrong. Unpriced models still have their tokens counted, and are named separately rather than counted as free. See Cost & limits.

titah bg

titah run --bg "run the full test suite and fix what fails"
titah bg list
titah bg logs bg_a490a57d -f
titah bg stop bg_a490a57d

See Background turns.

titah web

titah web
# http://127.0.0.1:53211

Starts the server and opens a browser client that uses exactly the API the TUI uses — no new routes. See Web client.

titah export and titah import

titah export -o bundle.json     # portable config, credentials left out and listed
titah import bundle.json        # show what it would change
titah import bundle.json -y     # apply it

Credentials are never written into a bundle. What was omitted is named in the output, so a config that arrives on a second machine says which keys still have to be set there rather than failing later with a missing-key error.

titah permission explain

titah permission explain bash "git push origin main"
titah permission explain network https://docs.python.org/3/

It calls the same function the agent loop calls (src/core/decide.ts), so what is explained can never differ from what runs. See Permissions & undo.

titah hooks list and titah plugin list

titah hooks list      # shell hooks from config, and which tools each matches
titah plugin list     # load the configured plugins and report what each provides

hooks list names invalid regexes explicitly — a hook silent because its pattern is broken looks exactly like a hook that did not match. See Hooks and Plugins.

Running headless from source

node src/cli.ts doctor
node src/cli.ts run "…"

Headless commands run straight from source. The TUI does not — Node cannot load .tsx, so it needs npm run build first.