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`	Stops the container, archives its timestamped logs under `.typeclaw/logs/`, then removes it.
`typeclaw status`	Container + daemon registration state.
`typeclaw stats`	Live resource snapshot for the container: cpu %, memory usage, and pid count (a `docker stats --no-stream` for this one agent).
`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.

Lifecycle removal paths (stop, restart, and stale-container cleanup during start) first save docker logs --timestamps to a unique <agent>/.typeclaw/logs/<container-id>-<timestamp>-<suffix>.log snapshot. Archives are retained for 14 days by default; set logs.retentionDays in typeclaw.json to a whole number from 1 through 3650 to change the age limit. Capture or retention failure preserves the Docker container instead of removing the only remaining log source. When Docker reports that it can no longer serve a dead or already-removing container's logs, TypeClaw warns, preserves prior snapshots, and continues with non-force removal. If the container remains stuck in removing, TypeClaw directs the operator to restart Docker or OrbStack; Docker restores it as dead, and the next start or restart can remove it normally. The local-only archive directory is gitignored and hidden from model-driven tools; the live typeclaw logs command continues to read the current Docker container.

Image builds retain only the latest successful local BuildKit cache for each agent and Docker daemon under ~/.typeclaw/build-cache. The isolated managed builder is removed after every attempt; cleanup is ownership-scoped and warnings do not block startup. If cache state is invalid, start prints the exact state directory to remove; if builder cleanup also failed, it prints the builder-removal command that must run first.

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 webex-bot
typeclaw channel add github
typeclaw channel add line
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 files or 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. For canonical paths worth mounting per use case, see Recommended mounts.

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