CLI Reference

The Thoth-ATO plugin exposes its slash commands inside Claude Code: /thoth (with the --remote flag for a remote cycle) and /thoth-config. A standalone thoth CLI for any terminal and CI pipelines is in pre-launch beta — installable from source today; it is published to npm at the v7.2 launch gate. Native VS Code and JetBrains extensions are on the roadmap.

/thoth — local cycle

Run a governed cycle locally in your editor. The plugin invokes Claude Code’s Write, Edit, and Bash tools directly. No network calls. No data leaves your machine. Unlimited on every plan, including Free.

Usage

/thoth <goal>
/thoth --spec <path-to-spec.md>
/thoth --github <issue-url>
/thoth --resume <cycle-id>

Flags

Flag	Type	Default	Description
<goal>	string	—	A natural-language goal. Quoted strings preserved verbatim.
--spec <path>	path	—	Read goal + constraints from a markdown spec file. Mutually exclusive with <goal>.
--github <url>	URL	—	Pull goal from a GitHub issue or PR URL. Auto-extracts title + body.
--resume <cycle-id>	string	—	Resume an interrupted cycle from its last checkpoint.
--max-cycles <n>	int	3	Cap the self-healing fix loop at n iterations.
--constitution <ref>	string	default	Use a named or hash-pinned constitution.
--no-gates	flag	off	Skip interactive approval gates. Not recommended. Useful only in fully scripted CI runs.
--verbose	flag	off	Stream every worker prompt and tool call to stdout.
--json	flag	off	Emit machine-readable progress events on stdout. Implies --no-gates.
--dry-run	flag	off	Run Specify + Plan phases only. Stop before Execute.

Exit codes

Code	Meaning
0	Cycle completed, signed verdict written.
1	Unexpected error (check .thoth/cycles/<id>/error.log).
2	User aborted at a gate.
3	Constitution violation — Judge refused to ship. Deliverable rejected.
4	Fix loop exceeded --max-cycles. Last attempt’s transcript preserved.
5	Spec validation failed (--spec path missing or malformed).
10	Plugin not authenticated (run /thoth-config set-api-key). Only emitted by --remote.
11	Signed-verdict quota reached — cycle completed but the verdict is unsigned (unsigned_quota_exceeded).
12	Network error reaching api.thothato.io.
13	Server-side error from remote console (5xx). Retried twice, then surfaced.

/thoth --remote — remote cycle

Run the same governed cycle but offload the Judge and Lead roles to the remote console at api.thothato.io. Workers still run in your editor. The remote receives only specs, plans, and verdict payloads — never your source code, never your secrets, never files on disk.

Usage

/thoth --remote <goal>
/thoth --remote --spec <path>

All /thoth flags also apply.

What’s sent to the remote

Sent	Not sent
Your natural-language goal	Your source files
Spec markdown (if you supplied one)	Your secrets / env vars
Task DAG (no code)	Your .git history
Principle scores during scoring	Your dependency tree contents
Deliverable hash (not the deliverable)	Your tool call outputs

Caution

Free tier: 50 signed verdicts per month; unsigned remote cycles and local cycles are unlimited. Pro / Team / Enterprise: unlimited signed verdicts. See pricing.

/thoth-config — configuration

Manage local plugin configuration. Secrets are stored in the OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager).

Subcommands

/thoth-config set-api-key <key>     # Store an API key in the OS keychain
/thoth-config show                  # Display non-secret config
/thoth-config clear                 # Wipe API key + cached state

set-api-key

/thoth-config set-api-key thk_...

Key format: thk_* (16+ characters). Get one at https://thothato.io/dashboard/settings. The key is written to the keychain and never echoed back.

show

Prints:

• Plugin version + build hash
• Active workspace path
• API endpoint (default https://api.thothato.io)
• Whether an API key is present (key value is never printed)
• Current constitution reference

Example output:

Thoth ATO 0.1.0
Workspace: /Users/you/code/myproject
API endpoint: https://api.thothato.io
API key: present (sk_live_a1b2 ...)
Constitution: default (sha256:abc...)

clear

Removes the API key from the keychain and deletes the cycle cache at ~/.thoth/cache. Does not delete .thoth/verdicts/ — verdicts are deliverable artifacts and belong to you, not the plugin.

Environment variables

The plugin and CLI read these from the environment. Useful for CI overrides.

Variable	Default	Description
THOTHATO_API_BASE	https://api.thothato.io	Override the remote console URL. Used for staging and self-hosted Enterprise.
THOTHATO_API_KEY	—	Override the keychain-stored API key. Useful in CI runners where keychain access is unavailable.
THOTH_LLM_PROVIDER	—	Provider for the full remote cycle. One of anthropic, openai, gemini, vertex, ollama, lmstudio, custom. Overridden by the --provider flag.
THOTH_LLM_MODEL	—	Model identifier for the selected provider. Overridden by the --model flag.
SONNET_MODEL	claude-sonnet-4-7	Override the worker model. Applies to local Claude Code mode only, where the loop runs on Claude; must be a Claude Code-compatible Sonnet identifier.
OPUS_MODEL	claude-opus-4-7	Override the Lead/Judge model in local Claude Code mode.
THOTHATO_CONSTITUTION	default	Override the constitution reference (named or sha256:...).
THOTHATO_MAX_CYCLES	3	Override the self-healing fix-loop cap.
THOTHATO_LOG_LEVEL	info	debug / info / warn / error.
THOTHATO_TELEMETRY	on	Set to off to disable anonymous usage telemetry. Telemetry never includes prompts, code, or filenames.
NO_COLOR	—	Set to any value to disable ANSI color output.

Selecting a provider for the full remote cycle

The full governed cycle runs on any supported provider — anthropic, openai, gemini, vertex, ollama, lmstudio, or custom — via the npm CLI plus the hosted control plane (thoth --remote). The local Claude Code plugin always runs the loop on Claude; SONNET_MODEL / OPUS_MODEL apply there only.

Provider selection follows this precedence (highest first):

1. --provider / --model CLI flags (per-invocation override)
2. THOTH_LLM_PROVIDER / THOTH_LLM_MODEL environment variables
3. The persisted default_provider in your credentials

Bring-your-own-key and self-hosted endpoints are supplied per request with --provider-key (never persisted) and --provider-endpoint.

Files written by the plugin

Path	Purpose
.thoth/verdicts/<cycle-id>.json	Signed verdict. Yours. Commit it, archive it.
.thoth/cycles/<cycle-id>/transcript.jsonl	Full worker prompt + tool-call transcript.
.thoth/cycles/<cycle-id>/plan.json	The approved DAG.
.thoth/cycles/<cycle-id>/spec.md	The resolved spec.
~/.thoth/cache/	Cross-cycle cache (skill manifests, constitution snapshots). Safe to delete.

What’s next?

• API reference — drive cycles programmatically from CI/CD.
• Verdict verification — verify the signed verdicts you just produced.
• Compliance — map verdicts to regulatory controls.