CLI & contract reference

Product version 1.0.1 · contract version 4.1.0.

Every toryo app exposes a subcommand CLI as its integration contract. Invoke it directly as toryo-<app> <command>, or through the umbrella binary as toryo <app> <command> (which dispatches to the sibling CLI). --help on any app prints its generated usage; toryo-<app> version --json reports the product + contract version a script can assert against.

This page is generated from the frozen contract, so it cannot drift from the CLIs.

Commands by app#

toryo#

• setup, provision ~/.toryo (dirs, host tools, config, DB, migrations, services)
  • [--runtime docker|pglite] [--no-services] [--dry-run] [--rc <path>]
  • [--database-mode local-docker|local-pglite|external] [--database-url <url>]
  • [--ollama-mode local|external] [--ollama-host <url>]
  • [--yes] accept every install offer; [--no-input] never prompt or install
  • [--install tmux,ollama,ollama-models|none] pre-answer the offers (for GUI callers)
• uninstall, remove toryo: services, binaries, shell PATH, skills, MCP registration
  • [--purge] also delete ~/.toryo and the docker volume (every database)
  • [--dry-run] [--yes] [--rc <path>]
• update, self-update: rebuild from source, or swap released binaries
  • [--check] [--notify] (with --check: send one messaging notice, apply nothing)
  • [--quiescence [--json]] report what an update would interrupt; exit 68 when busy
  • [--force] update even with jobs, runs or worker sessions in flight
• supervisor, operate the foreman watch supervisor (the LaunchAgent that keeps services up)
  • <status | stop | start>
• doctor, host preflight checklist (alias for foreman doctor)
• license, start a trial, activate, inspect, refresh, or drop this install’s license
  • <trial --email <email> | activate --email <email> <key>
  • | status [--json] | refresh | deactivate>
• knowledge, point this install at a team-hosted Postgres knowledge plane (shared brain)
  • <configure --url <url> | --clear | --brain-endpoint <url> | --clear-brain-endpoint
  • | provision | status [--json]>
• llm, point this install at a team-hosted llm-service (shared embedding + judge)
  • <configure --endpoint <url> | --clear | status [--json]>
• browser, point a worker’s browser MCP at your real logged-in Chrome via CDP
  • <configure --cdp-endpoint <url> | --clear | status [--json]>
• skills, install the toryo operator /-commands into the harness skills roots
  • <install [--dry-run] | uninstall | list [--json]>
• mcp, the umbrella MCP server, knowledge + control plane over stdio
  • <serve [--scope worker|operator|knowledge|local]>
• settings, install-wide settings, persisted to ~/.toryo/config.json
  • <describe | get | set [--database-mode MODE] [--database-url URL] [--ollama-mode MODE] [--ollama-host URL] [--telemetry true|false]>

toryo-brain#

• search, unified search across the four sources
  • --query Q [--project UUID] [--root PATH] [--home PATH]
  • [--sources memory,library,code-index,directives] [--k N]
• mcp, stdio MCP server (spawned by the worker)
  • [--tools all|knowledge|local]
• serve, HTTP MCP gateway: knowledge tools over /mcp, seat-gated (WS-C)
  • [--http-port 9800] [--auth-disabled]
• cleanup-project, lift + clear a removed project's knowledge (memory/library/code-index)
  • --project UUID [--apply]
• cleanup-orphans, sweep + clean knowledge of every removed project (safety net)
  • [--apply]
• migrate, bootstrap + apply tool-calls telemetry DB migrations

toryo-code-index#

• reindex, index a project tree; prints JSON (--project UUID --root PATH [--full])
• forget, drop every indexed row for a project (--project UUID)
• status, index status, one project or all ([--project UUID])
• file, one file plus its imports (--project UUID --path RELPATH)
• exporters, files exporting a symbol (--project UUID --symbol N)
• importers, files importing a file (--project UUID --path P)
• search, files matching a name/path substring (--project UUID --query S)
• migrate, apply pending DB migrations

toryo-completion#

• complete, run a subscription-backed structured-output completion; prints JSON
  • --prompt-file PATH --schema-file PATH [--model ID] [--effort LEVEL]
  • [--max-attempts N] [--priority N] [--timeout-ms N] [--out PATH]

toryo-db#

• up, bring the server up (build + start + wait for ready)
• down, stop the server (keeps volume)
• reset, stop + drop volume + restart (DESTROYS all app data)
• status, JSON: running + connection params
• logs, tail container logs
• psql, open psql against the running server

toryo-pglite#

• up, start the embedded runtime (spawn server, wait for ready)
• down, stop the embedded runtime
• status, JSON: running + runtime + databases + unready
• serve, run the server in the foreground (used by up)
• reset, stop + delete all embedded data + restart (DESTROYS data)

toryo-directives#

• received, launch-time directive snapshot for a worker as JSON
  • received <job-id>
• resolve, full directive stack as JSON
  • resolve <root> [--home PATH] [--project UUID]
• search, matching sections as a JSON array
  • search <root> --query Q [--home PATH] [--project UUID]
• list, {layer, path, claudeNative} inventory as JSON
  • list <root> [--home PATH] [--project UUID]

toryo-ideas#

• add, register an idea; prints JSON
  • --prompt TEXT [--scope global|project] [--project ref]
  • [--kind feature|process|rule-gap] [--impact N] [--effort N]
  • effort is [0, 1]; higher means more work. Both scores stamp source=triage
• drain-followups, file a session's recorded follow-ups as ideas; prints JSON
  • <file> [--project ref] [--scope global|project]
  • [--receipt F] [--out F] [--fail-open]
  • a receipt beside the artifact keeps a retry from filing anything twice
  • --fail-open reports an unreachable registry as failed entries, not exit 65
• list, list ideas; prints JSON array
  • [--scope global|project] [--project ref]
  • [--kind feature|process|rule-gap]
  • [--status open|promoted|dismissed|merged] [--include-merged]
  • merged rows are triage tombstones and are hidden unless asked for
• get, print one idea as JSON (get <id>)
• update, change an idea; prints JSON (update <id>)
  • [--prompt T] [--impact N | --clear-impact]
  • [--effort N | --clear-effort] effort is [0, 1]; higher means more work
  • [--triage-impact N] [--triage-effort N] machine scores, source=triage;
  • both are [0, 1] and never overwrite an operator-sourced axis
  • [--status open|promoted|dismissed|merged]
  • [--promoted-to REF | --clear-promoted-to]
  • [--clear-merged-into] reverses a triage merge; needs --status too
• dismiss, set status=dismissed (dismiss <id>)
• promote, set status=promoted, promoted_to=REF (promote <id> [--task REF])
• forget, drop a project's ideas (forget --project UUID)
• stats, ideas counts by project. JSON: {total, byProject}
  • [--out F]
• triage, merge near-duplicate ideas and rank what is left; prints JSON
  • [--dry-run] [--scope global|project] [--project ref]
  • [--kind feature|process|rule-gap] [--threshold N] [--out F]
  • merges apply unattended; this pass never closes an idea
• verify-dispatch, start an ideas-verify run per scope with flagged ideas; prints JSON
  • [--dry-run] [--max-runs N] [--max-ideas N] [--out F]
  • decides only what gets checked; the sequence does the checking
• verify-sweep, start an ideas-verify run for the ideas you name; prints JSON
  • --ids a,b,c (repeatable) [--dry-run] [--max-runs N] [--max-ideas N] [--out F]
  • the triage flag is not consulted; only open ideas are swept
  • every id given comes back under a target or in dropped, with a reason
• migrate, apply pending DB migrations

toryo-janitor#

• plan, dry-run preview; deletes nothing (JSON)
  • [--types T,..] [--before ISO]
• collect, run a pass; --apply actually deletes
  • [--apply] [--types T,..] [--before ISO] [--max N]
• status, recent audit passes (JSON)
  • [--limit N]
• settings, self-describing config
  • describe|get|set --<flag> V
• migrate, create DB + apply migrations

toryo-library#

• add, store an authored document; prints JSON
• import, import a docs directory (project or global)
• seed, write the documents toryo ships, if absent [--force]
• get, print one document as JSON (get <id|slug>)
• export, print one document as markdown with frontmatter (export <id>)
• list, list documents as a JSON array
• search, search documents (fts|semantic|hybrid)
• stats, aggregate stats as JSON ({total, byProject})
• update, patch a document; re-embeds on body change, --scope re-scopes (update <id>)
• remove, soft-delete a document (remove <id>)
• reembed, heal vectorless / stale-model documents [--dry-run]
• migrate, apply pending DB migrations

toryo-memory#

• remember, store a memory; prints JSON
• recall, rank memories for a query
• get, print one memory as JSON (get <id>)
• list, list memories as a JSON array
• count, count memories matching filters
• stats, aggregate memory stats as JSON
• forget, soft-delete a memory (forget <id>)
• pin, mark a memory decay-exempt (pin <id>)
• unpin, clear a memory decay exemption (unpin <id>)
• rate, record an outcome signal (rate <id> --signal 0..1)
• queue, global memories awaiting review
• approve, admit a pending memory (approve <id>)
• reject, reject a pending memory (reject <id>)
• decay, run one decay pass
• reembed, heal vectorless / stale-model memories [--dry-run]
• rejudge, re-run the global judge over pending memories [--dry-run]
• judge-session, attribute recall outcomes for a job
• signal-recall, deterministically signal a job's recalls
• populate-session, auto-populate memory from a session
• generalize-project, lift a removed project's durable memories to global, then clear them (--project <id> [--apply])
• migrate, apply pending DB migrations

toryo-messaging#

• start, run the daemon (foreground)
  • [--poll-ms N] [--http-port N]
• send, enqueue a message; prints id
  • --file P
• list, list messages newest-first
  • [--status S] [--source-app A] [--target-kind user|external|app]
  • [--limit N]
• get, print message JSON (get <id>)
• ack, acknowledge by id (ack <id> [--response JSON])
  • ack --source-app A --source-ref JSON [--response JSON]
  • ack --ids <id,id,…> [--response JSON], bulk; prints counts, not rows
• find-by-source-ref, list messages matching source-ref
  • --source-app A --source-ref JSON
• set-payload, overwrite a message payload
  • --id <id> --payload JSON
• mark-delivered, mark a pending message delivered (mark-delivered <id>)
• expire, mark a message expired (expire <id>)
• health, daemon up? JSON: {running, pid}
• migrate, apply pending DB migrations
• settings, describe | get | set --default-ttl-sec N

toryo-project#

• add, register a project; prints JSON
  • --name N --root P [--slug S] [--parent ref] [--no-index] [--docs-glob G]
• list, list projects; prints JSON array
• get, print one project as JSON (get <id|slug>)
• resolve, resolve a filesystem dir to its project; prints JSON
• update, change a project; prints JSON (update <id|slug>)
  • [--name N] [--root P] [--slug S] [--parent ref | --clear-parent]
  • [--index | --no-index] [--docs-glob G]
• descendants, print id set (self + descendants) as JSON
• remove, delete a project + clean its knowledge (remove <id|slug> [--no-cleanup])
• migrate, apply pending DB migrations

toryo-relay#

• send-message, push an inbox message (K: instruction|notification|alert)
  • --job-id J --kind K --body B [--forwarded-from M]
• inbox, read inbox, read-only (S: pending|delivered|consumed)
  • <jobId> [--status S]
• inbox-consume, list pending + mark delivered (worker poll target)
  • <jobId>
• inbox-deliver, mark named messages delivered (SessionStart injection's ack)
  • --job-id J --ids ID[,ID...]
• progress, append a progress event
  • --job-id J --message M
• progress-log, a job's progress log
  • <jobId>
• checkpoint, record a named milestone (X: JSON detail)
  • --job-id J --name N [--detail X]
• last-checkpoint, most recent checkpoint
  • <jobId>
• ask, ask the operator either/or questions, blocking until answered
  • --job-id J --questions-file F [--timeout-seconds N]
• questions, list questions (newest-first)
  • [<jobId>] [--open]
• answer, answer an open question (P: JSON number[][])
  • --id Q --picks P
• stalls, stall-detector output
  • [--open]
• status, daemon liveness + open-stall count (JSON)
• daemon, stall-detector singleton loop (foreman runs this)
• health, daemon liveness (JSON)
• settings, self-describing config
  • describe|get|set --<flag> V
• migrate, create DB + apply migrations

toryo-dispatch#

• start, run the daemon (foreground)
  • [--poll-ms 500] [--event-log-dir P] [--http-port 9790]
• enqueue, add a job; prints guid on stdout
  • --file P --caller C [--caller-job-id I]
  • [--priority 1-5] [--force] [--socket PATH]
• cancel, cancel a queued/running job (cancel <id>)
• status, print job JSON (status <id>)
• list, list jobs; prints JSON array
  • [--status S[,S]] [--caller C] [--project UUID] [--limit N] [--summary]
• events, print a job's lifecycle event timeline (events <jobId>)
• logs, print a job's worker event log as JSON (logs <jobId>)
  • [--tail N] [--out P]
• crashes, crash/failure projection; prints JSON
  • [--project UUID] [--since ISO] [--summary]
• conflicts, active write claims that collide with a candidate scope in <dir>; prints JSON
  • --dir <path> [--scope a,b,c]
• forget, drop a project's jobs + events (forget --project UUID)
  • live jobs are skipped; reported as skippedActive
• health, daemon up? JSON: {running, pid}
• stats, active slots + breakdown JSON (incl. byProject)
• circuit, provider circuit breaker state; JSON
  • [reset] close it now, re-allowing claims
• migrate, apply pending DB migrations
• settings, describe | get | set --max-concurrent N

toryo-scheduler#

• start, run the daemon (foreground)
  • [--tick-ms 1000] [--http-port 9791]
• schedule, create a new schedule; prints JSON
  • --file P --caller C
  • ( --at ISO | --cron EXPR [--timezone TZ] | --every DURATION )
  • [--name LABEL] [--caller-job-id ID] [--priority 1-5]
  • [--overlap skip|allow] [--misfire skip|fire-once]
• update, edit a schedule in place; prints JSON (update <id> [flags...])
  • (same flags as schedule; only those given change)
• list, list schedules; prints JSON array
  • [--status STATUS] [--project UUID]
• status, print one schedule as JSON (status <id>)
• history, list run history for a schedule (history <id> [--limit N])
• fire, run a schedule now; prints the run JSON (fire <id>)
• pause, pause an active schedule (pause <id>)
• resume, re-activate a paused schedule (resume <id>)
• delete, delete a schedule + its runs (delete <id>)
• health, daemon up? JSON: {running, pid}
• forget, drop a project's schedules (forget --project UUID)
• stats, schedules counts by project. JSON: {total, byProject}
  • [--out F]
• migrate, apply pending DB migrations

toryo-session-debugger#

• analyze, analyze one transcript; prints JSON
  • [<ref>] positional session|run|file.jsonl
  • [--file PATH] read a transcript file directly
  • [--session ID [--cwd DIR]] locate by session id
  • [--run JOBID] locate via a dispatch job workingDir
  • [--project UUID] attribute to a project (with --file)
  • [--no-capture] dry-run: detect + emit, no DB write
  • [--out PATH] write JSON to a file instead of stdout
  • [--duplicate-read-per-session N] already-covered reads of a path (dflt 1)
  • [--retry-loop-len N] consecutive same-tool fails (dflt 3)
  • [--failed-tool-per-session N] failures of one tool per run (dflt 3)
• report, aggregate persisted analyses; prints JSON
  • captures rule-gap ideas unless --no-capture
  • [--no-capture] [--out PATH]
• forget, drop a project's session analyses (forget --project UUID)
• stats, session analyses counts by project. JSON: {total, byProject}
  • [--out F]
• migrate, apply pending DB migrations

toryo-foreman#

• check, JSON report: green/red per service; exit 0 iff all green
• status, alias for check
• doctor, host preflight checklist (bun, docker, tmux, claude, …);
  • [--json] exit 0 iff every required check passes
• up, bring up whatever is down; waits until green
  • up [<service>] brings up that service + its deps only
• down, stop everything (reverse dependency order)
  • down [<service>] stops that service + its dependents only
• restart, bounce a service (and its transitive dependents);
  • no argument restarts every registered service
  • restart <service> queues behind a busy supervisor and runs once it drains
  • a service with in-flight work stops nothing: it defers and exits 75
  • [--force] bounces now, without waiting for anything to drain
• watch, daemon: hold lockfile, poll, restart anything red
  • [--interval-ms 5000]

toryo-usage#

• get, cached snapshots; re-polls stale ones (JSON)
  • [--provider id]
• poll, force a fresh poll, ignoring the TTL (JSON)
  • [--provider id]
• providers, registered providers + enabled state (JSON)
• settings, self-describing config
  • describe | get | set --<flag> V
• migrate, create DB + apply migrations

toryo-sequence#

• start, run the daemon (foreground)
  • [--tick-ms 500]
  • [--tick-concurrency 4]
  • [--reconcile-ms 30000]
  • [--http-port 9792]
  • (env TORYO_SEQUENCE_TICK_CONCURRENCY=<n> sets the same lane cap)
  • (env TORYO_SEQUENCE_WORKER_DEFAULTS=<json>
  • seeds worker payload defaults, e.g.
  • '{"llm":{"provider":"claude","model":"default"}}')
• list, available sequences (built-in + declarative)
  • [--project UUID|slug] also load that project’s .toryo/sequences
  • [--all-projects] include every registered project’s .toryo/sequences
  • [--include-system] include system-owned sequences (e.g. ideas-verify)
• describe, full spec of one sequence (describe <name>)
  • [--project UUID|slug] also load that project’s .toryo/sequences
  • [--all-projects] include every registered project’s .toryo/sequences
• validate, compile + check a declarative sequence file (validate <file.yaml>)
  • [--strict] fail on a step routing to a harness this host disabled
  • [--base-dir D] resolve a sandbox transform's sibling source from D
• transform, run one sandboxed transform against JSON (transform <file.yaml> --step <name>)
  • --step NAME the 'use: sandbox' transform step to run
  • [--input X] the threaded input: @file.json, - for stdin, or inline JSON
  • [--state X] run state {run, steps, project}: @file.json, -, or inline JSON
  • [--emit-types] write the sibling <source>.types.ts instead of running
• source, raw YAML of a declarative sequence (source <name>)
  • [--project UUID|slug] read that project’s .toryo/sequences
  • [--out F] write the YAML to F instead of stdout
• create, write a new declarative sequence (create <name>)
  • [--project UUID|slug] write into that project’s .toryo/sequences
  • [--file F] the source; omit to read stdin
• clone, copy a declarative sequence under a new name (clone <name> <newName>)
  • [--project UUID|slug] clone within that project’s .toryo/sequences
  • [--description TEXT] set the copy’s description: instead of inheriting
• edit, replace a declarative sequence's source (edit <name>)
  • [--project UUID|slug] edit within that project’s .toryo/sequences
  • [--file F] the new source; omit to read stdin
• delete, remove a declarative sequence file (delete <name>)
  • [--project UUID|slug] delete within that project’s .toryo/sequences
• import, fetch a remote sequence, review it, then write it (import <source>)
  • <source> owner/name, or a github blob URL, or an http(s) URL
  • [--path F] the file inside an owner/name repo
  • [--ref R] branch, tag or sha to resolve (github sources only)
  • [--project UUID|slug] write into that project’s .toryo/sequences
  • [--yes] accept without the review prompt
• install-shipped, write the sequences toryo ships into a sequences directory
  • [--project UUID|slug] install into that project’s .toryo/sequences
  • [--dry-run] report what would change, write nothing
  • [--upgrade-only] upgrade an installed copy; never install an absent one
  • an edited or foreign copy is reported and left alone, never overwritten
• run, create a run; prints {runId} (run <name> --input I)
  • [--project UUID]
  • [--working-dir PATH] root a project-less run (absolute path)
  • [--title T] [--description D]
  • [--depends-on A,C] hold run 'blocked' until those runs succeed
  • [--dry-run] validate input + project, create no run
• runs, list runs
  • [--sequence X] [--status S[,S]] [--project UUID[,UUID|none]]
  • [--archived exclude|only] omit for no archive constraint (the default)
  • [--limit N] [--order O] [--summary] [--out F]
• status, run + step history (status <runId>)
• update, patch a run's identity, or a pre-start run's inputs (update <runId>)
  • [--title T] [--description D] at any status
  • [--depends-on A,C] replace the whole set (pre-start only)
  • [--clear-depends-on] empty the set; the next reconcile promotes the run
  • [--input <json|@file>] revalidated against the run's pinned sequence
  • [--project UUID|slug] [--working-dir PATH]
  • [--re-pin] failed run only: re-point at the file on disk
  • [--re-pin --force] also a paused/failed run whose PIN no longer compiles, mid-graph
• ack, advance an awaiting-human step (ack <runId>)
  • [--data <json>] [--note ...]
• cancel, cancel a run + open steps (cancel <runId>)
• retry, re-arm a stuck/failed run's latest step (retry <runId> [--force])
  • --force also re-arms a parked worker step (the only lever an escalated run has)
• resume, paused → running (resume <runId>)
  • refuses a run parked on a human step; use ack, or retry --force
• archive, mark terminal runs as dealt with (archive <runId>… | archive --status S)
  • ids form: prints {archived, alreadyArchived, notTerminal, notFound}
  • a live run is refused (exit 68); the terminal ids in the same call still land
  • filtered form: [--status S[,S]] [--project UUID[,UUID|none]] [--sequence X] [--before ISO]
  • at least one narrowing flag is required, and ids do not combine with them
  • --before is measured on createdAt: finishedAt is nullable and would let rows escape
• unarchive, clear the archive stamp (unarchive <runId>…)
  • prints {unarchived, notArchived, notFound}; ids only, no filtered form
• settings, view/update settings (settings describe|get|set)
  • escalate-after-N, api-retry
• forget, drop a project's runs (forget --project UUID)
  • live runs are skipped; reported as skippedActive
• stats, run counts by project. JSON: {total, byProject}
  • [--out F]
• health, daemon up? JSON: {running, pid}
• migrate, apply pending DB migrations

Exit codes#

The shared convention:

toryo-completion (documented exception)

toryo-foreman (documented exception)

Environment variables#

Caller-set TORYO_* inputs external consumers may rely on (frozen in the contract):

• TORYO_DATABASE_URL
• TORYO_DATABASE_MODE
• TORYO_PG_HOST
• TORYO_PG_PORT
• TORYO_PG_USER
• TORYO_PG_PASSWORD
• TORYO_KNOWLEDGE_DATABASE_URL
• TORYO_KNOWLEDGE_PG_HOST
• TORYO_KNOWLEDGE_PG_PORT
• TORYO_KNOWLEDGE_PG_USER
• TORYO_KNOWLEDGE_PG_PASSWORD
• TORYO_KNOWLEDGE_APP_URL
• TORYO_KNOWLEDGE_APP_PG_HOST
• TORYO_KNOWLEDGE_APP_PG_PORT
• TORYO_KNOWLEDGE_APP_PG_USER
• TORYO_KNOWLEDGE_APP_PG_PASSWORD
• TORYO_LLM_ENDPOINT
• TORYO_BRAIN_PROJECT
• TORYO_BRAIN_ROOT
• TORYO_BRAIN_HOME
• TORYO_BRAIN_JOB
• TORYO_BRAIN_TENANT
• TORYO_BRAIN_USER
• TORYO_BRAIN_ENDPOINT
• TORYO_HOME
• TORYO_SUPERVISOR_LABEL
• TORYO_REPO
• TORYO_BIN_DIR
• TORYO_USE_BINARIES
• TORYO_UPDATE_CHANNEL
• TORYO_UPDATE_TOKEN
• TORYO_NO_UPDATE_BANNER
• TORYO_DB_RUNTIME
• TORYO_OLLAMA_MODE
• TORYO_OLLAMA_HOST
• TORYO_LICENSE_ENDPOINT
• TORYO_INSTALL_ID
• TORYO_LICENSE_EMAIL
• TORYO_CLAUDE_SKILLS_DIR
• TORYO_AGENTS_SKILLS_DIR
• TORYO_EXEC_STRATEGY
• TORYO_MULTIPLEXER
• TORYO_DISPATCH_CLI
• TORYO_BROWSER_CDP_ENDPOINT

SequenceSource (sequence) surface#

The externalized sequence surface is the SequenceDescriptor JSON emitted by toryo-sequence list | describe, plus these dispatch verbs:

run · ack · status · list · describe · cancel · retry · resume · update

Step kinds: worker · transform · human · setup.