TypeClaw runs code in three stages with different filesystems (/concepts/architecture). The CLI command names encode the stage. init creates the host stage; start/stop/restart/logs/tui/reload/shell etc. are host-stage launchers; run is the container-stage entrypoint Docker actually executes.

Lifecycle

Command	Description
`typeclaw init`	Interactive wizard. Scaffolds the agent folder; optionally wires the first provider + first channel.
`typeclaw start`	`docker run` with configured ports + mounts + env-file. Spawns `hostd` on first call per host. Flags: `--port`, `--build`.
`typeclaw restart`	`stop` + `start` with the same flag set as `start`.
`typeclaw stop`	`docker stop` then `docker rm` so a clean stop leaves no trace.
`typeclaw status`	Container + daemon registration state.
`typeclaw logs`	Print container stdout/stderr with reformatted local timestamps. `-f` / `--follow` to stream; `-n` / `--tail <N\|all>` to limit.
`typeclaw shell`	Drop into a shell inside the running container. `--shell` to pick (defaults to `bash` if present, else `sh`).
`typeclaw tui`	Attach an interactive TUI. Takes an optional one-shot prompt argument; `--url` to override the websocket URL.
`typeclaw reload`	Re-read `typeclaw.json` and apply hot-reloadable fields. Reports which fields require a restart.

--port is the preferred host port. On bind conflict, start allocates an ephemeral port; subsequent commands resolve the actual port by querying Docker. If Docker reports a published port but typeclaw reload cannot open that host websocket, reload falls back to a one-shot container-local websocket through docker exec and prints a repair hint; run typeclaw restart --port 0 when safe to repair host TUI/reload connectivity.

Providers

typeclaw provider add                              # interactive
typeclaw provider add fireworks --key fw_xxx
typeclaw provider add openai --oauth
typeclaw provider add openai --env MY_OPENAI_KEY   # bind to a custom env var
typeclaw provider set <id>                         # rotate
typeclaw provider remove <id> [--force]
typeclaw provider list                             # shows resolution: file vs env

Store: secrets.json#providers. See /concepts/secrets-policy.

Models

typeclaw model set default fireworks/kimi-k2
typeclaw model add deep anthropic/claude-opus-4-5
typeclaw model remove fast
typeclaw model list                                # current profiles
typeclaw model list --available                    # every known provider/model ref

Profiles (default, fast, deep, vision, or any custom name) map to a single ref or a fallback chain. Unknown profile names resolve to default with a one-time warning at session construction.

Roles

typeclaw role claim --as owner --channel slack-bot # pair a channel author
typeclaw role list                                 # show declared roles + match rules

--ttl (default 600000 ms) controls how long the claim code stays valid. Drop --channel to listen on every wired adapter.

A successful claim appends the match rule to typeclaw.json and reloads the running agent's config automatically — no typeclaw reload needed for the new role to take effect. The reload is best-effort: the role is already persisted, so if the reload fails the CLI says so and you can run typeclaw reload by hand. To grant a role to someone other than the current author, or to add a capability to a role, an owner/trusted user can also ask the agent directly via the grant_role tool from the TUI or a 1:1 DM (/reference/permissions#runtime-role-grants).

Channels

typeclaw channel add slack-bot
typeclaw channel add discord-bot
typeclaw channel add telegram-bot
typeclaw channel add github
typeclaw channel add kakaotalk
typeclaw channel set <adapter>                     # rotate credentials
typeclaw channel reauth kakaotalk                  # KakaoTalk's interactive re-login

Cron

typeclaw cron list
typeclaw cron list --json

Cron jobs are authored in cron.json; the CLI doesn't add/remove them. After editing the file, typeclaw reload.

Inspect

typeclaw inspect                                   # pick a session from a list
typeclaw inspect <session-id-or-prefix>            # replay then live-tail
typeclaw inspect --filter tool,assistant           # category filter (prefix with ! to exclude)
typeclaw inspect --since 5m                        # only events newer than 5m (forms: 30s, 5m, 1h, 7d)
typeclaw inspect <session> --json                  # one JSON event per line; requires an explicit session id

Replays the session's persisted transcript, then keeps the stream open and live-tails new events as they happen — no --follow toggle. Press Esc to return to the session picker; Ctrl+C exits. --json mode prints raw events without color or interactive controls.

Tunnels

typeclaw tunnel add <name> \
  --provider cloudflare-quick \
  --for-manual \
  --upstream-port 5173
typeclaw tunnel list
typeclaw tunnel status <name>
typeclaw tunnel logs <name>
typeclaw tunnel remove <name>

--for-manual flags the tunnel as user-owned. --for-channel <name> scopes it to an adapter's webhook.

Mounts

typeclaw mount list
typeclaw mount list --json
typeclaw mount add downloads ~/Downloads --read-only
typeclaw mount add work ./workspace --description "local worktree"
typeclaw mount remove downloads

Mounts expose host directories inside the container at /agent/mounts/<name>. Names must be lowercase alphanumeric with - or _. Adding/removing a mount updates typeclaw.json; restart the running agent with typeclaw restart for Docker to apply the bind mount.

Compose

typeclaw compose start
typeclaw compose start --build
typeclaw compose stop
typeclaw compose restart
typeclaw compose status
typeclaw compose logs -f
typeclaw compose usage --since 7d
typeclaw compose doctor
typeclaw compose doctor --fix --only docker,config

Thin loop over per-agent commands across every immediate subdirectory of cwd. Subdirectories whose name starts with . or _ are skipped, so you can park disabled or in-progress agents (e.g. _archived-coder/) next to live ones without compose touching them. No shared lifecycle. Beta — see /reference/compose for the full surface.

Doctor

typeclaw doctor                                    # human-readable report
typeclaw doctor -v                                 # per-check details
typeclaw doctor --json                             # for scripting
typeclaw doctor --fix                              # attempt auto-fixes and commit changes
typeclaw doctor --only docker,config               # narrow to categories

Categories: docker, config, secrets, network, git, plus per-plugin checks.

Update

typeclaw update                                    # update the installed CLI (auto-detect global vs local, Bun/npm/pnpm/yarn)
typeclaw update --manager bun                      # force Bun (scope is still auto-detected)
typeclaw update --manager npm                      # force npm (scope is still auto-detected)
typeclaw update --manager pnpm                     # force pnpm (scope is still auto-detected)
typeclaw update --manager yarn                     # force classic Yarn (scope is still auto-detected)
typeclaw update --dry-run                          # print the updater command without running it

Auto-detection recognizes these layouts:

Bun global (~/.bun/install/global/node_modules/typeclaw) → bun update -g typeclaw --latest.
npm global (.../lib/node_modules/typeclaw) → npm install -g typeclaw@latest.
pnpm global (.../pnpm/global/<N>/node_modules/typeclaw, or legacy .../{,.}pnpm-global/<N>/node_modules/typeclaw) → pnpm add -g typeclaw@latest.
classic Yarn global (.../yarn/global/node_modules/typeclaw) → yarn global upgrade typeclaw --latest.
Local install (any other node_modules/typeclaw) → drops the global flag and runs in the project root that owns the node_modules/. The manager is picked from the lockfile next to that root (bun.lock / bun.lockb → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm; bun wins ties).

--manager always overrides the detected manager. The scope (global or not) still follows the detected install layout, so --manager=npm against a local install runs npm install typeclaw@latest (no -g), not a stealth global update. Source checkouts have no detectable layout and fall back to a global update — pass --manager to pick the registry side.

Usage

typeclaw usage                                     # summary across recent sessions
typeclaw usage daily --since 7d                    # one row per calendar day
typeclaw usage session --limit 20                  # top sessions by cost
typeclaw usage models                              # one row per provider/model
typeclaw usage origin                              # by session origin
typeclaw usage --json

Common flags: --since <duration>, --until <iso>, --cwd <path>, --json.

Hidden commands

Command	Notes
`typeclaw _hostd`	Host-side daemon, spawned automatically by the first `start`. Hidden from `--help`. State at `~/.typeclaw/` (override with `TYPECLAW_HOME`).
`typeclaw run`	Container-stage entrypoint. Docker executes this; the host CLI never invokes it directly.

CLI

On this page