CLI Commands Reference

This page covers the terminal commands you run from your shell.

For in-chat slash commands, see Slash Commands Reference.

Global entrypoint

thoth [global-options] <command> [subcommand/options]

Global options

Option	Description
--version, -V	Show version and exit.
--profile <name>, -p <name>	Select which Thoth profile to use for this invocation. Overrides the sticky default set by thoth profile use.
--resume <session>, -r <session>	Resume a previous session by ID or title.
--continue [name], -c [name]	Resume the most recent session, or the most recent session matching a title.
--worktree, -w	Start in an isolated git worktree for parallel-agent workflows.
--yolo	Bypass dangerous-command approval prompts.
--pass-session-id	Include the session ID in the agent's system prompt.
--ignore-user-config	Ignore ~/.thoth/config.yaml and fall back to built-in defaults. Credentials in .env are still loaded.
--ignore-rules	Skip auto-injection of AGENTS.md, SOUL.md, .cursorrules, memory, and preloaded skills.

Top-level commands

Command	Purpose
thoth chat	Interactive or one-shot chat with the agent.
thoth model	Interactively choose the default provider and model.
thoth fallback	Manage fallback providers tried when the primary model errors.
thoth gateway	Run or manage the messaging gateway service.
thoth proxy	Local OpenAI-compatible proxy that attaches OAuth provider credentials. See Subscription Proxy.
thoth lsp	Manage Language Server Protocol integration (semantic diagnostics for write_file/patch).
thoth setup	Interactive setup wizard for all or part of the configuration.
thoth whatsapp	Configure and pair the WhatsApp bridge.
thoth slack	Slack helpers (currently: generate the app manifest with every command as a native slash).
thoth auth	Manage credentials — add, list, remove, reset, set strategy. Handles OAuth flows for Codex/Nous/Anthropic.
thoth login / logout	Deprecated — use thoth auth instead.
thoth status	Show agent, auth, and platform status.
thoth cron	Inspect and tick the cron scheduler.
thoth kanban	Multi-profile collaboration board (tasks, links, dispatcher).
thoth webhook	Manage dynamic webhook subscriptions for event-driven activation.
thoth hooks	Inspect, approve, or remove shell-script hooks declared in config.yaml.
thoth doctor	Diagnose config and dependency issues.
thoth dump	Copy-pasteable setup summary for support/debugging.
thoth debug	Debug tools — upload logs and system info for support.
thoth backup	Back up Thoth home directory to a zip file.
thoth checkpoints	Inspect / prune / clear ~/.thoth/checkpoints/ (the shadow store used by /rollback). Run with no args for a status overview.
thoth import	Restore a Thoth backup from a zip file.
thoth logs	View, tail, and filter agent/gateway/error log files.
thoth config	Show, edit, migrate, and query configuration files.
thoth pairing	Approve or revoke messaging pairing codes.
thoth skills	Browse, install, publish, audit, and configure skills.
thoth bundles	Group several skills under a single /<name> slash command. See Skill Bundles.
thoth curator	Background skill maintenance — status, run, pause, pin. See Curator.
thoth memory	Configure external memory provider. Plugin-specific subcommands (e.g. thoth honcho) register automatically when their provider is active.
thoth acp	Run Thoth as an ACP server for editor integration.
thoth mcp	Manage MCP server configurations and run Thoth as an MCP server.
thoth plugins	Manage Thoth Agent plugins (install, enable, disable, remove).
thoth tools	Configure enabled tools per platform.
thoth computer-use	Install or check the cua-driver backend (macOS Computer Use).
thoth sessions	Browse, export, prune, rename, and delete sessions.
thoth insights	Show token/cost/activity analytics.
thoth claw	OpenClaw migration helpers.
thoth dashboard	Launch the web dashboard for managing config, API keys, and sessions.
thoth profile	Manage profiles — multiple isolated Thoth instances.
thoth completion	Print shell completion scripts (bash/zsh/fish).
thoth version	Show version information.
thoth update	Pull latest code and reinstall dependencies (git installs), or check PyPI and pip install --upgrade (pip installs). --check previews without installing; --backup takes a pre-pull THOTH_HOME snapshot.
thoth uninstall	Remove Thoth from the system.

thoth chat

thoth chat [options]

Common options:

Option	Description
-q, --query "..."	One-shot, non-interactive prompt.
-m, --model <model>	Override the model for this run.
-t, --toolsets <csv>	Enable a comma-separated set of toolsets.
--provider <provider>	Force a provider: auto, openrouter, nous, openai-codex, copilot-acp, copilot, anthropic, gemini, google-gemini-cli, huggingface, novita, zai, kimi-coding, kimi-coding-cn, minimax, minimax-cn, minimax-oauth, kilocode, xiaomi, arcee, gmi, alibaba, alibaba-coding-plan (alias alibaba_coding), deepseek, nvidia, ollama-cloud, xai (alias grok), xai-oauth (alias grok-oauth), qwen-oauth, bedrock, opencode-zen, opencode-go, ai-gateway, azure-foundry, lmstudio, stepfun, tencent-tokenhub (alias tencent, tokenhub).
-s, --skills <name>	Preload one or more skills for the session (can be repeated or comma-separated).
-v, --verbose	Verbose output.
-Q, --quiet	Programmatic mode: suppress banner/spinner/tool previews.
--image <path>	Attach a local image to a single query.
--resume <session> / --continue [name]	Resume a session directly from chat.
--worktree	Create an isolated git worktree for this run.
--checkpoints	Enable filesystem checkpoints before destructive file changes.
--yolo	Skip approval prompts.
--pass-session-id	Pass the session ID into the system prompt.
--ignore-user-config	Ignore ~/.thoth/config.yaml and use built-in defaults. Credentials in .env are still loaded. Useful for isolated CI runs, reproducible bug reports, and third-party integrations.
--ignore-rules	Skip auto-injection of AGENTS.md, SOUL.md, .cursorrules, persistent memory, and preloaded skills. Combine with --ignore-user-config for a fully isolated run.
--source <tag>	Session source tag for filtering (default: cli). Use tool for third-party integrations that should not appear in user session lists.
--max-turns <N>	Maximum tool-calling iterations per conversation turn (default: 90, or agent.max_turns in config).

Examples:

thoth
thoth chat -q "Summarize the latest PRs"
thoth chat --provider openrouter --model anthropic/claude-sonnet-4.6
thoth chat --toolsets web,terminal,skills
thoth chat --quiet -q "Return only JSON"
thoth chat --worktree -q "Review this repo and open a PR"
thoth chat --ignore-user-config --ignore-rules -q "Repro without my personal setup"

thoth -z <prompt> — scripted one-shot

For programmatic callers (shell scripts, CI, cron, parent processes piping in a prompt), thoth -z is the purest one-shot entry point: single prompt in, final response text out, nothing else on stdout or stderr. No banner, no spinner, no tool previews, no Session: line — just the agent's final reply as plain text.

thoth -z "What's the capital of France?"
# → Paris.

# Parent scripts can cleanly capture the response:
answer=$(thoth -z "summarize this" < /path/to/file.txt)

Per-run overrides (no mutation to ~/.thoth/config.yaml):

Flag	Equivalent env var	Purpose
-m / --model <model>	THOTH_INFERENCE_MODEL	Override the model for this run
--provider <provider>	THOTH_INFERENCE_PROVIDER	Override the provider for this run

thoth -z "…" --provider openrouter --model openai/gpt-5.5
# or:
THOTH_INFERENCE_MODEL=anthropic/claude-sonnet-4.6 thoth -z "…"

Same agent, same tools, same skills — just strips every interactive / cosmetic layer. If you need tool output in the transcript too, use thoth chat -q instead; -z is explicitly for "I only want the final answer".

thoth model

Interactive provider + model selector. This is the command for adding new providers, setting up API keys, and running OAuth flows. Run it from your terminal — not from inside an active Thoth chat session.

thoth model

Use this when you want to:

• add a new provider (OpenRouter, Anthropic, Copilot, DeepSeek, custom, etc.)
• log into OAuth-backed providers (Anthropic, Copilot, Codex, Nous Portal)
• enter or update API keys
• pick from provider-specific model lists
• configure a custom/self-hosted endpoint
• save the new default into config

thoth model vs /model — know the difference

thoth model (run from your terminal, outside any Thoth session) is the full provider setup wizard. It can add new providers, run OAuth flows, prompt for API keys, and configure endpoints.

/model (typed inside an active Thoth chat session) can only switch between providers and models you've already set up. It cannot add new providers, run OAuth, or prompt for API keys.

If you need to add a new provider: Exit your Thoth session first (Ctrl+C or /quit), then run thoth model from your terminal prompt.

/model slash command (mid-session)

Switch between already-configured models without leaving a session:

/model                              # Show current model and available options
/model claude-sonnet-4              # Switch model (auto-detects provider)
/model zai:glm-5                    # Switch provider and model
/model custom:qwen-2.5              # Use model on your custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Use a named custom provider
/model openrouter:anthropic/claude-sonnet-4  # Switch back to cloud

By default, /model changes apply to the current session only. Add --global to persist the change to config.yaml:

/model claude-sonnet-4 --global     # Switch and save as new default

What if I only see OpenRouter models?

If you've only configured OpenRouter, /model will only show OpenRouter models. To add another provider (Anthropic, DeepSeek, Copilot, etc.), exit your session and run thoth model from the terminal.

Provider and base URL changes are persisted to config.yaml automatically. When switching away from a custom endpoint, the stale base URL is cleared to prevent it leaking into other providers.

thoth gateway

thoth gateway <subcommand>

Subcommands:

Subcommand	Description
run	Run the gateway in the foreground. Recommended for WSL, Docker, and Termux.
start	Start the installed systemd/launchd background service.
stop	Stop the service (or foreground process).
restart	Restart the service.
status	Show service status.
list	List all profiles and whether each profile's gateway is currently running (with PID where available). Handy when you run multiple profiles side-by-side and want a single overview.
install	Install as a systemd (Linux) or launchd (macOS) background service.
uninstall	Remove the installed service.
setup	Interactive messaging-platform setup.

Options:

Option	Description
--all	On start / restart / stop: act on every profile's gateway, not just the active THOTH_HOME. Useful if you run multiple profiles side-by-side and want to restart them all after thoth update.

WSL users

Use thoth gateway run instead of thoth gateway start — WSL's systemd support is unreliable. Wrap it in tmux for persistence: tmux new -s thoth 'thoth gateway run'. See WSL FAQ for details.

thoth lsp

thoth lsp <subcommand>

Manage the Language Server Protocol integration. LSP runs real language servers (pyright, gopls, rust-analyzer, …) in the background and feeds their diagnostics into the post-write check used by write_file and patch. Gated on git workspace detection — LSP only runs when the cwd or edited file is inside a git worktree.

Subcommands:

Subcommand	Description
status	Show service state, configured servers, install status.
list	Print the registry of supported servers. Pass --installed-only to skip missing ones.
install <id>	Eagerly install one server's binary.
install-all	Install every server with a known auto-install recipe.
restart	Tear down running clients so the next edit re-spawns.
which <id>	Print the resolved binary path for one server.

See LSP — Semantic Diagnostics for the full guide, supported languages, and configuration knobs.

thoth setup

thoth setup [model|tts|terminal|gateway|tools|agent] [--non-interactive] [--reset] [--quick] [--reconfigure]

First run: launches the first-time wizard.

Returning user (already configured): drops straight into the full reconfigure wizard — every prompt shows your current value as its default, press Enter to keep or type a new value. No menu.

Jump into one section instead of the full wizard:

Section	Description
model	Provider and model setup.
terminal	Terminal backend and sandbox setup.
gateway	Messaging platform setup.
tools	Enable/disable tools per platform.
agent	Agent behavior settings.

Options:

Option	Description
--quick	On returning-user runs: only prompt for items that are missing or unset. Skip items you already have configured.
--non-interactive	Use defaults / environment values without prompts.
--reset	Reset configuration to defaults before setup.
--reconfigure	Backwards-compat alias — bare thoth setup on an existing install now does this by default.

thoth whatsapp

thoth whatsapp

Runs the WhatsApp pairing/setup flow, including mode selection and QR-code pairing.

thoth slack

thoth slack manifest              # print manifest to stdout
thoth slack manifest --write      # write to ~/.thoth/slack-manifest.json
thoth slack manifest --slashes-only  # just the features.slash_commands array

Generates a Slack app manifest that registers every gateway command in COMMAND_REGISTRY (/btw, /stop, /model, …) as a first-class Slack slash command — matching Discord and Telegram parity. Paste the output into your Slack app config at https://api.slack.com/apps → your app → Features → App Manifest → Edit, then Save. Slack prompts for reinstall if scopes or slash commands changed.

Flag	Default	Purpose
--write [PATH]	stdout	Write to a file instead of stdout. Bare --write writes $THOTH_HOME/slack-manifest.json.
--name NAME	Thoth	Bot display name in Slack.
--description DESC	default blurb	Bot description shown in the Slack app directory.
--slashes-only	off	Emit only features.slash_commands for merging into a manually-maintained manifest.

Run thoth slack manifest --write again after thoth update to pick up any new commands.

thoth login / thoth logout (Deprecated)

caution

thoth login has been removed. Use thoth auth to manage OAuth credentials, thoth model to select a provider, or thoth setup for full interactive setup.

thoth auth

Manage credential pools for same-provider key rotation. See Credential Pools for full documentation.

thoth auth                                              # Interactive wizard
thoth auth list                                         # Show all pools
thoth auth list openrouter                              # Show specific provider
thoth auth add openrouter --api-key sk-or-v1-xxx        # Add API key
thoth auth add anthropic --type oauth                   # Add OAuth credential
thoth auth remove openrouter 2                          # Remove by index
thoth auth reset openrouter                             # Clear cooldowns
thoth auth status anthropic                             # Show auth status for a provider
thoth auth logout anthropic                             # Log out and clear stored auth state
thoth auth spotify                                      # Authenticate Thoth with Spotify via PKCE

Subcommands: add, list, remove, reset, status, logout, spotify. When called with no subcommand, launches the interactive management wizard.

thoth status

thoth status [--all] [--deep]

Option	Description
--all	Show all details in a shareable redacted format.
--deep	Run deeper checks that may take longer.

thoth cron

thoth cron <list|create|edit|pause|resume|run|remove|status|tick>

Subcommand	Description
list	Show scheduled jobs.
create / add	Create a scheduled job from a prompt, optionally attaching one or more skills via repeated --skill.
edit	Update a job's schedule, prompt, name, delivery, repeat count, or attached skills. Supports --clear-skills, --add-skill, and --remove-skill.
pause	Pause a job without deleting it.
resume	Resume a paused job and compute its next future run.
run	Trigger a job on the next scheduler tick.
remove	Delete a scheduled job.
status	Check whether the cron scheduler is running.
tick	Run due jobs once and exit.

thoth kanban

thoth kanban [--board <slug>] <action> [options]

Multi-profile, multi-project collaboration board. Each install can host many boards (one per project, repo, or domain); each board is a standalone queue with its own SQLite DB and dispatcher scope. New installs start with one board called default, whose DB is ~/.thoth/kanban.db for back-compat; additional boards live at ~/.thoth/kanban/boards/<slug>/kanban.db. The gateway-embedded dispatcher sweeps every board per tick.

Global flags (apply to every action below):

Flag	Purpose
--board <slug>	Operate on a specific board. Defaults to the current board (set via thoth kanban boards switch, the THOTH_KANBAN_BOARD env var, or default).

This is the human / scripting surface. Agent workers spawned by the dispatcher drive the board through a dedicated kanban_* toolset (kanban_show, kanban_complete, kanban_block, kanban_create, kanban_link, kanban_comment, kanban_heartbeat; orchestrator profiles also get kanban_list and kanban_unblock) instead of shelling to thoth kanban. Workers have THOTH_KANBAN_BOARD pinned in their env so they physically cannot see other boards.

Action	Purpose
init	Create kanban.db if missing. Idempotent.
boards list / boards ls	List all boards with task counts. --json, --all (include archived).
boards create <slug>	Create a new board. Flags: --name, --description, --icon, --color, --switch (make active). Slug is kebab-case, auto-downcased.
boards switch <slug> / boards use	Persist <slug> as the active board (writes ~/.thoth/kanban/current).
boards show / boards current	Print the currently-active board's name, DB path, and task counts.
boards rename <slug> "<name>"	Change a board's display name. Slug is immutable.
boards rm <slug>	Archive (default) or hard-delete a board. --delete skips the archive step. Archived boards move to boards/_archived/<slug>-<ts>/. Refused for default.
create "<title>"	Create a new task on the active board. Flags: --body, --assignee, --parent (repeatable), --workspace scratch|worktree|dir:<path>, --tenant, --priority, --triage, --idempotency-key, --max-runtime, --max-retries, --skill (repeatable).
list / ls	List tasks on the active board. Filter with --mine, --assignee, --status, --tenant, --archived, --json.
show <id>	Show a task with comments and events. --json for machine output.
assign <id> <profile>	Assign or reassign. Use none to unassign. Refused while task is running.
link <parent> <child>	Add a dependency. Cycle-detected. Both tasks must be on the same board.
unlink <parent> <child>	Remove a dependency.
claim <id>	Atomically claim a ready task. Prints resolved workspace path.
comment <id> "<text>"	Append a comment. The next worker that claims the task reads it as part of its kanban_show() response.
complete <id>	Mark task done. Flags: --result, --summary, --metadata.
block <id> "<reason>"	Mark task blocked for human input. Also appends the reason as a comment.
schedule <id> "<reason>"	Park time-delay/follow-up work in scheduled so it is not shown as a human blocker.
unblock <id>	Return a blocked or scheduled task to ready (or todo if dependencies are still open).
archive <id>	Hide from default list. gc will remove scratch workspaces.
tail <id>	Follow a task's event stream.
dispatch	One dispatcher pass on the active board. Flags: --dry-run, --max N, --failure-limit N, --json.
context <id>	Print the full context a worker would see (title + body + parent results + comments).
specify <id> / specify --all	Flesh out a triage-column task into a concrete spec (title + body with goal, approach, acceptance criteria) via the auxiliary LLM, then promote it to todo. Flags: --tenant (scope --all to one tenant), --author, --json. Configure the model under auxiliary.triage_specifier in config.yaml.
decompose <id> / decompose --all	Fan a triage-column task out into a graph of child tasks routed to specialist profiles by description (the orchestrator-driven path). Falls back to specify-style single-task promotion when the LLM decides the task doesn't benefit from fan-out. Same flags as specify. Configure the model under auxiliary.kanban_decomposer in config.yaml. Also runs automatically every dispatcher tick when kanban.auto_decompose: true (the default). See Auto vs Manual orchestration.
gc	Remove scratch workspaces for archived tasks.

Examples:

# Create a second board and put a task on it without switching away.
thoth kanban boards create atm10-server --name "ATM10 Server" --icon 🎮
thoth kanban --board atm10-server create "Restart server" --assignee ops

# Switch the active board for subsequent calls.
thoth kanban boards switch atm10-server
thoth kanban list                  # shows atm10-server tasks

# Archive a board (recoverable) or hard-delete it.
thoth kanban boards rm atm10-server
thoth kanban boards rm atm10-server --delete

Board resolution order (highest precedence first): --board <slug> flag → THOTH_KANBAN_BOARD env var → ~/.thoth/kanban/current file → default.

All actions are also available as a slash command in the gateway (/kanban …), with the same argument surface — including boards subcommands and the --board flag.

For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see docs/thoth-kanban-v1-spec.pdf in the repository or the Kanban user guide.

thoth webhook

thoth webhook <subscribe|list|remove|test>

Manage dynamic webhook subscriptions for event-driven agent activation. Requires the webhook platform to be enabled in config — if not configured, prints setup instructions.

Subcommand	Description
subscribe / add	Create a webhook route. Returns the URL and HMAC secret to configure on your service.
list / ls	Show all agent-created subscriptions.
remove / rm	Delete a dynamic subscription. Static routes from config.yaml are not affected.
test	Send a test POST to verify a subscription is working.

thoth webhook subscribe

thoth webhook subscribe <name> [options]

Option	Description
--prompt	Prompt template with {dot.notation} payload references.
--events	Comma-separated event types to accept (e.g. issues,pull_request). Empty = all.
--description	Human-readable description.
--skills	Comma-separated skill names to load for the agent run.
--deliver	Delivery target: log (default), telegram, discord, slack, github_comment.
--deliver-chat-id	Target chat/channel ID for cross-platform delivery.
--secret	Custom HMAC secret. Auto-generated if omitted.
--deliver-only	Skip the agent — deliver the rendered --prompt as the literal message. Zero LLM cost, sub-second delivery. Requires --deliver to be a real target (not log).

Subscriptions persist to ~/.thoth/webhook_subscriptions.json and are hot-reloaded by the webhook adapter without a gateway restart.

thoth doctor

thoth doctor [--fix]

Option	Description
--fix	Attempt automatic repairs where possible.

thoth dump

thoth dump [--show-keys]

Outputs a compact, plain-text summary of your entire Thoth setup. Designed to be copy-pasted into Discord, GitHub issues, or Telegram when asking for support — no ANSI colors, no special formatting, just data.

Option	Description
--show-keys	Show redacted API key prefixes (first and last 4 characters) instead of just set/not set.

What it includes

Section	Details
Header	Thoth version, release date, git commit hash
Environment	OS, Python version, OpenAI SDK version
Identity	Active profile name, THOTH_HOME path
Model	Configured default model and provider
Terminal	Backend type (local, docker, ssh, etc.)
API keys	Presence check for all 22 provider/tool API keys
Features	Enabled toolsets, MCP server count, memory provider
Services	Gateway status, configured messaging platforms
Workload	Cron job counts, installed skill count
Config overrides	Any config values that differ from defaults

Example output

--- thoth dump ---
version:          0.8.0 (2026.4.8) [af4abd2f]
os:               Linux 6.14.0-37-generic x86_64
python:           3.11.14
openai_sdk:       2.24.0
profile:          default
thoth_home:       ~/.thoth
model:            anthropic/claude-opus-4.6
provider:         openrouter
terminal:         local

api_keys:
  openrouter           set
  openai               not set
  anthropic            set
  nous                 not set
  firecrawl            set
  ...

features:
  toolsets:           all
  mcp_servers:        0
  memory_provider:    built-in
  gateway:            running (systemd)
  platforms:          telegram, discord
  cron_jobs:          3 active / 5 total
  skills:             42

config_overrides:
  agent.max_turns: 250
  compression.threshold: 0.85
  display.streaming: True
--- end dump ---

When to use

• Reporting a bug on GitHub — paste the dump into your issue
• Asking for help in Discord — share it in a code block
• Comparing your setup to someone else's
• Quick sanity check when something isn't working

tip

thoth dump is specifically designed for sharing. For interactive diagnostics, use thoth doctor. For a visual overview, use thoth status.

thoth debug

thoth debug share [options]

Upload a debug report (system info + recent logs) to a paste service and get a shareable URL. Useful for quick support requests — includes everything a helper needs to diagnose your issue.

Option	Description
--lines <N>	Number of log lines to include per log file (default: 200).
--expire <days>	Paste expiry in days (default: 7).
--local	Print the report locally instead of uploading.

The report includes system info (OS, Python version, Thoth version), recent agent and gateway logs (512 KB limit per file), and redacted API key status. Keys are always redacted — no secrets are uploaded.

Paste services tried in order: paste.rs, dpaste.com.

Examples

thoth debug share              # Upload debug report, print URL
thoth debug share --lines 500  # Include more log lines
thoth debug share --expire 30  # Keep paste for 30 days
thoth debug share --local      # Print report to terminal (no upload)

thoth backup

thoth backup [options]

Create a zip archive of your Thoth configuration, skills, sessions, and data. The backup excludes the thoth-agent codebase itself.

Option	Description
-o, --output <path>	Output path for the zip file (default: ~/thoth-backup-<timestamp>.zip).
-q, --quick	Quick snapshot: only critical state files (config.yaml, state.db, .env, auth, cron jobs). Much faster than a full backup.
-l, --label <name>	Label for the snapshot (only used with --quick).

The backup uses SQLite's backup() API for safe copying, so it works correctly even when Thoth is running (WAL-mode safe).

What's excluded from the zip:

• *.db-wal, *.db-shm, *.db-journal — SQLite's WAL / shared-memory / journal sidecars. The *.db file already got a consistent snapshot via sqlite3.backup(); shipping the live sidecars alongside it would let a restore see a half-committed state.
• checkpoints/ — per-session trajectory caches. Hash-keyed and regenerated per session; wouldn't port cleanly to another install anyway.
• The thoth-agent code itself (this is a user-data backup, not a repo snapshot).

Examples

thoth backup                           # Full backup to ~/thoth-backup-*.zip
thoth backup -o /tmp/thoth.zip        # Full backup to specific path
thoth backup --quick                   # Quick state-only snapshot
thoth backup --quick --label "pre-upgrade"  # Quick snapshot with label

thoth checkpoints

thoth checkpoints [COMMAND]

Inspect and manage the shadow git store at ~/.thoth/checkpoints/ — the storage layer behind the in-session /rollback command. Safe to run any time; does not require the agent to be running.

Subcommand	Description
status (default)	Show total size, project count, and per-project breakdown. Bare thoth checkpoints is equivalent.
list	Alias for status.
prune	Force a cleanup sweep — delete orphan and stale projects, GC the store, enforce the size cap. Ignores the 24h idempotency marker.
clear	Delete the entire checkpoint base. Irreversible; asks for confirmation unless -f.
clear-legacy	Delete only the legacy-<timestamp>/ archives produced by the v1→v2 migration.

Options

Option	Subcommand	Description
--limit N	status, list	Max projects to list (default 20).
--retention-days N	prune	Drop projects whose last_touch is older than N days (default 7).
--max-size-mb N	prune	After the orphan/stale pass, drop the oldest commit per project until total store size ≤ N MB (default 500).
--keep-orphans	prune	Skip deleting projects whose working directory no longer exists.
-f, --force	clear, clear-legacy	Skip the confirmation prompt.

Examples

thoth checkpoints                                  # status overview
thoth checkpoints prune --retention-days 3         # aggressive cleanup
thoth checkpoints prune --max-size-mb 200          # tighten size cap once
thoth checkpoints clear-legacy -f                  # drop v1 archive dirs
thoth checkpoints clear -f                         # wipe everything

See Checkpoints and /rollback for the full architecture and the in-session commands.

thoth import

thoth import <zipfile> [options]

Restore a previously created Thoth backup into your Thoth home directory. All files in the archive overwrite existing files in your Thoth home; --force only skips the confirmation prompt that fires when the target already has a Thoth installation.

Option	Description
-f, --force	Skip the existing-installation confirmation prompt.

warning

Stop the gateway before importing to avoid conflicts with running processes.

Examples

thoth import ~/thoth-backup-20260423.zip           # Prompts before overwriting existing config
thoth import ~/thoth-backup-20260423.zip --force   # Overwrite without prompting

thoth logs

thoth logs [log_name] [options]

View, tail, and filter Thoth log files. All logs are stored in ~/.thoth/logs/ (or <profile>/logs/ for non-default profiles).

Log files

Name	File	What it captures
agent (default)	agent.log	All agent activity — API calls, tool dispatch, session lifecycle (INFO and above)
errors	errors.log	Warnings and errors only — a filtered subset of agent.log
gateway	gateway.log	Messaging gateway activity — platform connections, message dispatch, webhook events

Options

Option	Description
log_name	Which log to view: agent (default), errors, gateway, or list to show available files with sizes.
-n, --lines <N>	Number of lines to show (default: 50).
-f, --follow	Follow the log in real time, like tail -f. Press Ctrl+C to stop.
--level <LEVEL>	Minimum log level to show: DEBUG, INFO, WARNING, ERROR, CRITICAL.
--session <ID>	Filter lines containing a session ID substring.
--since <TIME>	Show lines from a relative time ago: 30m, 1h, 2d, etc. Supports s (seconds), m (minutes), h (hours), d (days).
--component <NAME>	Filter by component: gateway, agent, tools, cli, cron.

Examples

# View the last 50 lines of agent.log (default)
thoth logs

# Follow agent.log in real time
thoth logs -f

# View the last 100 lines of gateway.log
thoth logs gateway -n 100

# Show only warnings and errors from the last hour
thoth logs --level WARNING --since 1h

# Filter by a specific session
thoth logs --session abc123

# Follow errors.log, starting from 30 minutes ago
thoth logs errors --since 30m -f

# List all log files with their sizes
thoth logs list

Filtering

Filters can be combined. When multiple filters are active, a log line must pass all of them to be shown:

# WARNING+ lines from the last 2 hours containing session "tg-12345"
thoth logs --level WARNING --since 2h --session tg-12345

Lines without a parseable timestamp are included when --since is active (they may be continuation lines from a multi-line log entry). Lines without a detectable level are included when --level is active.

Log rotation

Thoth uses Python's RotatingFileHandler. Old logs are rotated automatically — look for agent.log.1, agent.log.2, etc. The thoth logs list subcommand shows all log files including rotated ones.

thoth config

thoth config <subcommand>

Subcommands:

Subcommand	Description
show	Show current config values.
edit	Open config.yaml in your editor.
set <key> <value>	Set a config value.
path	Print the config file path.
env-path	Print the .env file path.
check	Check for missing or stale config.
migrate	Add newly introduced options interactively.

thoth pairing

thoth pairing <list|approve|revoke|clear-pending>

Subcommand	Description
list	Show pending and approved users.
approve <platform> <code>	Approve a pairing code.
revoke <platform> <user-id>	Revoke a user's access.
clear-pending	Clear pending pairing codes.

thoth skills

thoth skills <subcommand>

Subcommands:

Subcommand	Description
browse	Paginated browser for skill registries.
search	Search skill registries.
install	Install a skill.
inspect	Preview a skill without installing it.
list	List installed skills.
check	Check installed hub skills for upstream updates.
update	Reinstall hub skills with upstream changes when available.
audit	Re-scan installed hub skills.
uninstall	Remove a hub-installed skill.
reset	Un-stick a bundled skill flagged as user_modified by clearing its manifest entry. With --restore, also replaces the user copy with the bundled version.
publish	Publish a skill to a registry.
snapshot	Export/import skill configurations.
tap	Manage custom skill sources.
config	Interactive enable/disable configuration for skills by platform.

Common examples:

thoth skills browse
thoth skills browse --source official
thoth skills search react --source skills-sh
thoth skills search https://mintlify.com/docs --source well-known
thoth skills inspect official/security/1password
thoth skills inspect skills-sh/vercel-labs/json-render/json-render-react
thoth skills install official/migration/openclaw-migration
thoth skills install skills-sh/anthropics/skills/pdf --force
thoth skills install https://sharethis.chat/SKILL.md                     # Direct URL (single-file SKILL.md)
thoth skills install https://example.com/SKILL.md --name my-skill        # Override name when frontmatter has none
thoth skills check
thoth skills update
thoth skills config
thoth skills reset google-workspace
thoth skills reset google-workspace --restore --yes

Notes:

• --force can override non-dangerous policy blocks for third-party/community skills.
• --force does not override a dangerous scan verdict.
• --source skills-sh searches the public skills.sh directory.
• --source well-known lets you point Thoth at a site exposing /.well-known/skills/index.json.
• --source browse-sh searches browse.sh's catalog of 200+ site-specific browser-automation skills. Identifiers look like browse-sh/airbnb.com/search-listings-ddgioa.
• Passing an http(s)://…/*.md URL installs a single-file SKILL.md directly. When frontmatter has no name: and the URL slug isn't a valid identifier, an interactive terminal prompts for a name; non-interactive surfaces (/skills install in chat, gateway platforms) require --name <x> instead.

thoth bundles

thoth bundles <subcommand>

Skill bundles group several skills under one /<bundle-name> slash command. Invoking the bundle loads every referenced skill into a single combined user message. Storage: ~/.thoth/skill-bundles/<slug>.yaml. See Skill Bundles for the YAML schema and behavior.

Subcommands:

Subcommand	Description
list	List installed bundles (default when no subcommand given)
show <name>	Show one bundle's name, description, skills, and file path
create <name>	Create a new bundle. Pass --skill <id> (repeat) or omit for interactive entry. --description, --instruction, --force available.
delete <name>	Remove a bundle file
reload	Re-scan ~/.thoth/skill-bundles/ and report added/removed bundles

Examples:

thoth bundles create backend-dev \
  --skill github-code-review \
  --skill test-driven-development \
  --skill github-pr-workflow \
  -d "Backend feature work"

thoth bundles list
thoth bundles show backend-dev
thoth bundles delete backend-dev

In a chat session, /bundles lists installed bundles and /<bundle-name> loads one.

thoth curator

thoth curator <subcommand>

The curator is an auxiliary-model background task that periodically reviews agent-created skills, prunes stale ones, consolidates overlaps, and archives obsolete skills. Bundled and hub-installed skills are never touched. Archives are recoverable; auto-deletion never happens.

Subcommand	Description
status	Show curator status and skill stats
run	Trigger a curator review now (blocks until the LLM pass finishes)
run --background	Start the LLM pass in a background thread and return immediately
run --dry-run	Preview only — produce the review report with no mutations
backup	Take a manual tar.gz snapshot of ~/.thoth/skills/ (curator also snapshots automatically before every real run)
rollback	Restore ~/.thoth/skills/ from a snapshot (defaults to newest)
rollback --list	List available snapshots
rollback --id <ts>	Restore a specific snapshot by id
rollback -y	Skip the confirmation prompt
pause	Pause the curator until resumed
resume	Resume a paused curator
pin <skill>	Pin a skill so the curator never auto-transitions it
unpin <skill>	Unpin a skill
restore <skill>	Restore an archived skill
archive <skill>	Archive a skill manually
prune	Manually prune skills the curator would normally clean up
list-archived	List archived skills (recoverable via restore)

On a fresh install the first scheduled pass is deferred by one full interval_hours (7 days by default) — the gateway will not curate immediately on the first tick after thoth update. Use thoth curator run --dry-run to preview before that happens.

See Curator for behavior and config.

thoth fallback

thoth fallback <subcommand>

Manage the fallback provider chain. Fallback providers are tried in order when the primary model fails with rate-limit, overload, or connection errors.

Subcommand	Description
list (alias: ls)	Show the current fallback chain (default when no subcommand)
add	Pick a provider + model (same picker as thoth model) and append to the chain
remove (alias: rm)	Pick an entry to delete from the chain
clear	Remove all fallback entries

See Fallback Providers.

thoth hooks

thoth hooks <subcommand>

Inspect shell-script hooks declared in ~/.thoth/config.yaml, test them against synthetic payloads, and manage the first-use consent allowlist at ~/.thoth/shell-hooks-allowlist.json.

Subcommand	Description
list (alias: ls)	List configured hooks with matcher, timeout, and consent status
test <event>	Fire every hook matching <event> against a synthetic payload
revoke (aliases: remove, rm)	Remove a command's allowlist entries (takes effect on next restart)
doctor	Check each configured hook: exec bit, allowlist, mtime drift, JSON validity, and synthetic run timing

See Hooks for event signatures and payload shapes.

thoth memory

thoth memory <subcommand>

Set up and manage external memory provider plugins. Available providers: honcho, openviking, mem0, hindsight, holographic, retaindb, byterover, supermemory. Only one external provider can be active at a time. Built-in memory (MEMORY.md/USER.md) is always active.

Subcommands:

Subcommand	Description
setup	Interactive provider selection and configuration.
status	Show current memory provider config.
off	Disable external provider (built-in only).

Provider-specific subcommands

When an external memory provider is active, it may register its own top-level thoth <provider> command for provider-specific management (e.g. thoth honcho when Honcho is active). Inactive providers do not expose their subcommands. Run thoth --help to see what's currently wired in.

thoth acp

thoth acp

Starts Thoth as an ACP (Agent Client Protocol) stdio server for editor integration.

Related entrypoints:

thoth-acp
python -m acp_adapter

Install support first:

pip install -e '.[acp]'

See ACP Editor Integration and ACP Internals.

thoth mcp

thoth mcp <subcommand>

Manage MCP (Model Context Protocol) server configurations and run Thoth as an MCP server.

Subcommand	Description
serve [-v|--verbose]	Run Thoth as an MCP server — expose conversations to other agents.
add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth|header]	Add an MCP server with automatic tool discovery.
remove <name> (alias: rm)	Remove an MCP server from config.
list (alias: ls)	List configured MCP servers.
test <name>	Test connection to an MCP server.
configure <name> (alias: config)	Toggle tool selection for a server.
login <name>	Force re-authentication for an OAuth-based MCP server.

See MCP Config Reference, Use MCP with Thoth, and MCP Server Mode.

thoth plugins

thoth plugins [subcommand]

Unified plugin management — general plugins, memory providers, and context engines in one place. Running thoth plugins with no subcommand opens a composite interactive screen with two sections:

• General Plugins — multi-select checkboxes to enable/disable installed plugins
• Provider Plugins — single-select configuration for Memory Provider and Context Engine. Press ENTER on a category to open a radio picker.

Subcommand	Description
(none)	Composite interactive UI — general plugin toggles + provider plugin configuration.
install <identifier> [--force]	Install a plugin from a Git URL or owner/repo.
update <name>	Pull latest changes for an installed plugin.
remove <name> (aliases: rm, uninstall)	Remove an installed plugin.
enable <name>	Enable a disabled plugin.
disable <name>	Disable a plugin without removing it.
list (alias: ls)	List installed plugins with enabled/disabled status.

Provider plugin selections are saved to config.yaml:

• memory.provider — active memory provider (empty = built-in only)
• context.engine — active context engine ("compressor" = built-in default)

General plugin disabled list is stored in config.yaml under plugins.disabled.

See Plugins and Build a Thoth Plugin.

thoth tools

thoth tools [--summary]

Option	Description
--summary	Print the current enabled-tools summary and exit.

Without --summary, this launches the interactive per-platform tool configuration UI.

thoth computer-use

thoth computer-use <subcommand>

Subcommands:

Subcommand	Description
install	Run the upstream cua-driver installer (macOS only).
install --upgrade	Re-run the installer even if cua-driver is already on PATH. The upstream script always pulls the latest release, so this performs an in-place upgrade.
status	Print whether cua-driver is on $PATH and which version is installed.

thoth computer-use install is the stable entry point for installing the cua-driver binary used by the computer_use toolset. It runs the same upstream installer that thoth tools invokes when you first enable Computer Use, so it's safe to use for re-running the install if the toolset toggle didn't trigger it (for example, on returning-user setups).

thoth update automatically re-runs the upstream installer at the end of the update if cua-driver is on PATH, so most users will not need to call --upgrade manually. Use it when upstream ships a fix you want right now without waiting for the next Thoth update.

thoth sessions

thoth sessions <subcommand>

Subcommands:

Subcommand	Description
list	List recent sessions.
browse	Interactive session picker with search and resume.
export <output> [--session-id ID]	Export sessions to JSONL.
delete <session-id>	Delete one session.
prune	Delete old sessions.
stats	Show session-store statistics.
rename <session-id> <title>	Set or change a session title.

thoth insights

thoth insights [--days N] [--source platform]

Option	Description
--days <n>	Analyze the last n days (default: 30).
--source <platform>	Filter by source such as cli, telegram, or discord.

thoth claw

thoth claw migrate [options]

Migrate your OpenClaw setup to Thoth. Reads from ~/.openclaw (or a custom path) and writes to ~/.thoth. Automatically detects legacy directory names (~/.clawdbot, ~/.moltbot) and config filenames (clawdbot.json, moltbot.json).

Option	Description
--dry-run	Preview what would be migrated without writing anything.
--preset <name>	Migration preset: full (all compatible settings) or user-data (excludes infrastructure config). Neither preset imports secrets — pass --migrate-secrets explicitly.
--overwrite	Overwrite existing Thoth files on conflicts (default: refuse to apply when the plan has conflicts).
--migrate-secrets	Include API keys in migration. Required even under --preset full.
--no-backup	Skip the pre-migration zip snapshot of ~/.thoth/ (by default a single restore-point archive is written to ~/.thoth/backups/pre-migration-*.zip before apply; restorable with thoth import).
--source <path>	Custom OpenClaw directory (default: ~/.openclaw).
--workspace-target <path>	Target directory for workspace instructions (AGENTS.md).
--skill-conflict <mode>	Handle skill name collisions: skip (default), overwrite, or rename.
--yes	Skip the confirmation prompt.

What gets migrated

The migration covers 30+ categories across persona, memory, skills, model providers, messaging platforms, agent behavior, session policies, MCP servers, TTS, and more. Items are either directly imported into Thoth equivalents or archived for manual review.

Directly imported: SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills (4 source directories), default model, custom providers, MCP servers, messaging platform tokens and allowlists (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), agent defaults (reasoning effort, compression, human delay, timezone, sandbox), session reset policies, approval rules, TTS config, browser settings, tool settings, exec timeout, command allowlist, gateway config, and API keys from 3 sources.

Archived for manual review: Cron jobs, plugins, hooks/webhooks, memory backend (QMD), skills registry config, UI/identity, logging, multi-agent setup, channel bindings, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.

API key resolution checks three sources in priority order: config values → ~/.openclaw/.env → auth-profiles.json. All token fields handle plain strings, env templates (${VAR}), and SecretRef objects.

For the complete config key mapping, SecretRef handling details, and post-migration checklist, see the full migration guide.

Examples

# Preview what would be migrated
thoth claw migrate --dry-run

# Full migration (all compatible settings, no secrets)
thoth claw migrate --preset full

# Full migration including API keys
thoth claw migrate --preset full --migrate-secrets

# Migrate user data only (no secrets), overwrite conflicts
thoth claw migrate --preset user-data --overwrite

# Migrate from a custom OpenClaw path
thoth claw migrate --source /home/user/old-openclaw

thoth dashboard

thoth dashboard [options]

Launch the web dashboard — a browser-based UI for managing configuration, API keys, and monitoring sessions. Requires pip install thoth-agent[web] (FastAPI + Uvicorn). The embedded browser Chat tab requires --tui plus the pty extra. See Web Dashboard for full documentation.

Option	Default	Description
--port	9119	Port to run the web server on
--host	127.0.0.1	Bind address
--no-open	—	Don't auto-open the browser
--tui	off	Enable the in-browser Chat tab — embeds a browser terminal running the classic REPL behind a PTY/WebSocket bridge. Requires pip install 'thoth-agent[web,pty]' and a POSIX PTY environment such as Linux, macOS, or WSL2.
--insecure	off	Allow binding to non-localhost hosts. Exposes dashboard credentials on the network; use only behind trusted network controls.
--stop	—	Stop running thoth dashboard processes and exit.
--status	—	List running thoth dashboard processes and exit.

# Default — opens browser to http://127.0.0.1:9119
thoth dashboard

# Custom port, no browser
thoth dashboard --port 8080 --no-open

# Enable the browser Chat tab
thoth dashboard --tui

thoth profile

thoth profile <subcommand>

Manage profiles — multiple isolated Thoth instances, each with its own config, sessions, skills, and home directory.

Subcommand	Description
list	List all profiles.
use <name>	Set a sticky default profile.
create <name> [--clone] [--clone-all] [--clone-from <source>] [--no-alias]	Create a new profile. --clone copies config, .env, and SOUL.md from the active profile. --clone-all copies all state. --clone-from specifies a source profile.
delete <name> [-y]	Delete a profile.
show <name>	Show profile details (home directory, config, etc.).
alias <name> [--remove] [--name NAME]	Manage wrapper scripts for quick profile access.
rename <old> <new>	Rename a profile.
export <name> [-o FILE]	Export a profile to a .tar.gz archive (local backup).
import <archive> [--name NAME]	Import a profile from a .tar.gz archive (local restore).
install <source> [--name N] [--alias] [--force] [-y]	Install a profile distribution from a git URL or local directory.
update <name> [--force-config] [-y]	Re-pull a distribution; preserves user data (memories, sessions, auth).
info <name>	Show a profile's distribution manifest (version, requirements, source).

Examples:

thoth profile list
thoth profile create work --clone
thoth profile use work
thoth profile alias work --name h-work
thoth profile export work -o work-backup.tar.gz
thoth profile import work-backup.tar.gz --name restored
thoth profile install github.com/user/my-distro --alias
thoth profile update work
thoth -p work chat -q "Hello from work profile"

thoth completion

thoth completion [bash|zsh|fish]

Print a shell completion script to stdout. Source the output in your shell profile for tab-completion of Thoth commands, subcommands, and profile names.

Examples:

# Bash
thoth completion bash >> ~/.bashrc

# Zsh
thoth completion zsh >> ~/.zshrc

# Fish
thoth completion fish > ~/.config/fish/completions/thoth.fish

thoth update

thoth update [--check] [--backup] [--restart-gateway]

Pulls the latest thoth-agent code and reinstalls dependencies in your venv, then re-runs the post-install hooks (MCP servers, skills sync, completion install). Safe to run on a live install.

pip installs: thoth update detects pip-based installations automatically — it queries PyPI for the latest release and runs pip install --upgrade thoth-agent instead of git pull. PyPI releases track tagged versions (major/minor releases), not every commit on main. Use --check to see if a newer PyPI release is available without installing.

Option	Description
--check	Print the current commit and the latest origin/main commit side by side, and exit 0 if in sync or 1 if behind. Does not pull, install, or restart anything.
--backup	Create a labeled pre-update snapshot of THOTH_HOME (config, auth, sessions, skills, pairing data) before pulling. Default is off — the previous always-backup behavior was adding minutes to every update on large homes. Flip it on permanently via update.backup: true in config.yaml.
--restart-gateway	After a successful update, restart the running gateway service. Implies --all semantics if multiple profiles are installed.

Additional behavior:

• Pairing data snapshot. Even when --backup is off, thoth update takes a lightweight snapshot of ~/.thoth/pairing/ before git pull. You can roll it back with thoth backup restore --state pre-update if a pull rewrites a file you were editing.
• Legacy hermes.service warning. If Thoth detects a pre-rename hermes.service systemd unit (instead of the current thoth-gateway.service), it prints a one-time migration hint so you can avoid flap-loop issues.
• Exit codes. 0 on success, 1 on pull/install/post-install errors, 2 on unexpected working-tree changes that block git pull.

Maintenance commands

Command	Description
thoth version	Print version information.
thoth update	Pull latest changes and reinstall dependencies.
thoth uninstall [--full] [--yes]	Remove Thoth, optionally deleting all config/data.

See also

• Slash Commands Reference
• CLI Interface
• Sessions
• Skills System
• Skins & Themes