Skip to main content

CLI reference

Root help is captured from orchestrator/bin/timon --help with a disposable TIMON_HOME, an unreachable API target and a 20-second process limit. No daemon or subcommand is started. Additional usage blocks are read from literal source strings because subcommand help is not universally safe to execute. Legacy French prose is translated and command syntax is retained; descriptions then go through the publication policy in scripts/doc-policy.json.

This is a reference snapshot, not a shell script to execute in full. Replace placeholders with real values. Installation, task creation, deletion and service commands change the target instance.

Root help

timon — Timon control plane CLI

Agents & missions:
timon list list agents (json)
timon spawn <agent> <input...> start a mission, returns {mission_id}
[--extra-skills s1,s2] inject skills for this spawn only
[--extra-mcp mcp1,mcp2] inject MCP servers for this spawn only
[--allow "Bash(timon:*)"] pre-allow tool patterns for this spawn
timon send <mission_id> <input...> send a follow-up to a running mission
timon wait <mission_id> [--timeout=120] block until done, print assistant text
timon status <mission_id> full mission detail
timon kill <mission_id> terminate a running mission
timon trace <traceId|missionId> [--json]
timon trace backfill [--days N] explicitly replay cold events into spans

timon agent create <name> [flags] new agent (prompt via --prompt-file or stdin)
timon agent update <name> [flags] partial update (omit prompt to leave unchanged)
flags: --backend NAME --model SLUG --permission-mode MODE
--cwd PATH --project SLUG
--skills a,b,c --mcp-servers a,b (repeatable or comma-sep)
--allowed-tools … --disallowed-tools … --excluded-mcp-servers …
(deletion is manual: rm -rf ~/.timon/agents/<name>/)
timon agent set-scope <name> <scope> set memory scope (NONE|SESSION|AGENT|GLOBAL)

timon mission summarize <id> [--force] compress the mission transcript for cross-LLM continuation
timon mission fork <id> --to <agent> [--message "..."]
spawn a continuation on another agent, seeded with summary
timon mission search <text…> full-text search in mission history
[--agent NAME] [--project SLUG] [--since 7d|ISO] [--until …] [--limit N] [--json]
timon mission reindex [--batch N] rebuild the mission search index

Skills (~/.timon/skills/<id>/SKILL.md):
timon skill list list installed skills
timon skill get <id> print the SKILL.md body
timon skill put <id> [--file PATH] upsert; content from --file or stdin
timon skill rm <id> delete

MCP servers (~/.timon/mcp/<id>.json):
timon mcp list list installed MCP servers
timon mcp get <id> print the full config (json)
timon mcp put <id> [--file PATH] upsert; JSON from --file or stdin
(shape: {name?, description?, transport})
timon mcp rm <id> delete

Tasks (Kanban backlog):
timon task list [--status PENDING|IN_PROGRESS|DONE|BLOCKED] (TODO = deprecated alias of PENDING)
timon task get <id>
timon task create --title TEXT --agent NAME [--type code|review|merge|research|doc|chore] [--project SLUG] [--description D] [--priority 1-5]
[--base BRANCH]
[--model SLUG] [--permission-mode default|acceptEdits|bypassPermissions]
[--fallback-backend NAME|none] [--fallback-model SLUG]
[--deps id1,id2] [--scheduled ISO8601]
[--extra-skills s1,s2] [--extra-mcp mcp1,mcp2]
[--allow "Bash(timon:*),Read(/tmp/*)"]
timon task done <id> [--comment TEXT | --comment-file PATH | --comment-stdin] [--merged-sha SHA]
timon task block <id> --reason TEXT
timon task mark-as-done [id] --comment TEXT|--comment-file PATH|--comment-stdin [--verdict pass|changes_requested] [--merged-sha SHA]
closes THE current mission's task (no id to copy)
timon task mark-as-failed [id] --reason TEXT closes it as BLOCKED
timon task update <id> [--status ...] [--priority N] [--title ...] [--agent ...] [--type ...]
timon task delete <id>

timon backends [--json] backends and models actually available

Series fallback plan (quota exhausted during a project):
timon series fallback list [--series ID] rules in effect (default: THIS mission's series)
timon series fallback set --scope orchestrator|code|review|merge|doc|chore|*
--backend NAME [--model SLUG] [--series ID] [--no-apply]
--backend none → this scope does not fall back
applied at once to the pending tasks of that scope;
--no-apply records the rule without moving anything
timon series fallback clear --scope SCOPE [--series ID]

Series role choices (who runs, for THIS series only — roles.json untouched):
timon series role list [--series ID] choices in effect for the series
timon series role set --scope code|review|merge|research|doc|chore
[--backend NAME] [--model SLUG] [--series ID]
task override > series role > project role > agent config
timon series role clear --scope SCOPE [--series ID]

Worktrees (git isolation per code task):
timon worktree info <task-id> show path/branch/base/merged-sha
timon worktree create <task-id> [--base B] force-create (dispatcher does it automatically for type=code)
timon worktree dispose <task-id> [--force] unmounts worktree + local branch (post-merge)

Projects (agent roles per project):
timon project list lists configured projects
timon project roles <slug> shows the role→agent mapping
timon project set-role <slug> <role> <agent> [--model SLUG] [--permission-mode MODE]
sets the agent + model/permission for a role

Routines (cron → creates a Kanban task on each due tick):
timon routine list
timon routine create --name TEXT --agent NAME --cron EXPR --prompt TEXT [--type ...] [--project SLUG]
timon routine update <id> [--cron ...] [--enabled true|false] ...
timon routine delete <id>

Pipelines (multi-agent workflow templates → Kanban tasks):
timon pipeline list
timon pipeline get <id>
timon pipeline create --name TEXT --file pipeline.json [--description D]
timon pipeline run <id> [--input JSON | --input-file PATH]
timon pipeline run-status <run_id>
timon pipeline delete <id>

Agent messages (async inbox — doesn't block the parent's tokens):
timon msg send <to_agent> <payload...> fire-and-forget to an agent's inbox
[--kind msg|request|response]
[--in-reply-to <msg_id>]
[--to-mission <mid>]
timon msg recv [--to <agent>] [--from <agent>] [--status pending|picked] [--limit N]
timon msg pick <message_id> marks picked + returns the payload (atomic)
timon msg reply <message_id> <payload...> sends a response to the message's from_agent

Notifications (human center — sidebar canvas):
timon notify report <title…> [--body TEXT] [--task-id ID] end-of-task report, result
timon notify alert <title…> [--body TEXT] [--urgent] [--task-id ID] blocking alert
timon notify action_required <title…> [--body TEXT] [--urgent] (rarely manual — auto via permissions)
--mission-id is auto-injected from TIMON_MISSION_ID if not provided.

PROJECT TO DO (a project's idea notebook — nothing here is ever dispatched):
timon project-todo list [--status open|done|promoted|all] [--project SLUG] [--json]
timon project-todo add <text...> [--project SLUG] [--notes TEXT]
timon project-todo update <id> [<text...>] [--project SLUG] [--notes TEXT] [--status open|done]
timon project-todo done <id> [--undo] checks / unchecks the idea
timon project-todo promote <id> --agent NAME [--type TYPE] [--priority N] [--base REF] [--pipeline P]
the idea becomes a PENDING task, and keeps the link to it
timon project-todo rm <id>

Users (superadmin / daemon-token — out-of-band reset and invitations):
timon user list accounts (json)
timon user reset-password <email-or-id> temporary password, printed once
timon user disable <email-or-id> status=disabled, sessions dropped
timon user enable <email-or-id>
timon user invite --email EMAIL --name NAME [--group ID] [--superadmin]
invitation token, printed once
timon user add-group <email-or-id> --group ID
timon user remove-group <email-or-id> --group ID
timon user groups <email-or-id> groups this user belongs to (json)
timon role list roles and their permissions (json)
timon role catalog permissions offered by /roles (json)
timon group list groups, their roles and member count (json)
timon group set-roles <group-id> --roles id1,id2,...

Secrets vault (write-only: no command ever prints a stored value):
timon secret list [--project SLUG] [--agent NAME] [--json]
timon secret set <NAME> [--scope global|project:<slug>|agent:<name>]
[--mode inject|broker] [--note TEXT] --stdin
the value is ALWAYS piped on stdin, never an argument:
printf %s "$TOKEN" | timon secret set GITHUB_TOKEN --scope global --stdin
no --scope at all = the daemon alone, which no agent ever receives.
timon secret grant <NAME> --scope … opens it to one more scope
timon secret revoke <NAME> --scope … closes that scope again
timon secret rm <NAME>
timon secret rekey new master key, staged then promoted
timon secret import-env [--delete-source] imports ~/.timon/secrets.env, no grant

Memory (rules injected into agents — DIRECT write to the database):
timon memory rule add <text…> [--scope agent|project|role|global] [--agent NAME]
[--project SLUG] [--role ROLE]
[--kind pitfall|decision|preference] [--tier normal|core]
[--text-file PATH] [--json]
defaults: --scope agent, --kind pitfall, agent = $TIMON_AGENT, project = $TIMON_PROJECT.
An exact duplicate on the same scope is refused (exit 3).
timon memory rule list [--scope …] [--agent NAME] [--project SLUG] [--json]
timon memory rule rm <id>
timon memory search <query…> cross-cutting search (rules + facts)
timon memory overview counters + pending proposals
timon memory show <project|agent> <id> [file] reads the reference .md files

Project's embedded browser:
timon browser status [<slug>] [--json] does the project have a browser up?
timon browser start [<slug>] starts it (persistent profile, sessions kept)
timon browser stop [<slug>] stops it (the profile itself survives)
timon browser list [--json] all known sessions
default slug: $TIMON_PROJECT, otherwise derived from cwd.

Resources (anti-saturation guard for the machine):
timon export [--out F] [--with-archive] portable archive of ~/.timon (secrets excluded)
timon import F [--to DIR] [--force] restores an archive on this machine
timon backup enable nightly routine 03:30 (export, 7 archives)
timon backup status [--json] state, next run, archives under backups/
timon doctor [--json] binaries, host capabilities, config

Third-party plugins (hot-loaded, no daemon restart):
timon plugin list [--json] installed, version, enabled, refused
timon plugin add <spec> [--yes] npm install (name, .tgz or dir)
timon plugin remove <id> npm uninstall (data kept)
timon plugin enable <id> | disable <id> toggles in timon.config.json
timon plugin sign <dir> signs with ~/.timon-signing/plugins.key
timon plugin verify <id> verifies without loading the plugin

Web app served by the daemon (NEVER an orchestrator restart):
timon app status [--json] module active? app built? child alive?
timon app restart signals the web-app child, daemon relaunches it

Daemon service (systemd user unit on Linux, launchd agent on macOS,
scheduled task at logon on Windows):
timon service install [--dry-run] writes the unit/plist and starts it
timon service uninstall stops and removes it, ~/.timon untouched
timon service status [--json] installed? running?

Bundled modules (writes timon.config.json — effective on next daemon boot):
timon module list [--json] catalog, wanted state, actual state + reason
timon module enable <name> | disable <name> toggles in timon.config.json

Secrets broker (the daemon acts, you never hold the value):
git config credential.helper "timon git-credential"
git then authenticates through the
vault: no token in a remote URL,
a command line or the environment

Licence:
timon license status shows your licence status, edition and expiry date
timon license deactivate release this machine (the seat transfers once its last token lease expires)
timon license install <file> installs a licence file
timon license activate <key> activates Timon with your licence key

timon health [--json] day/night profile, Timon cgroups memory
and CPU, live missions, OOM

Google agenda (all calendars on the account, aggregated in one call):
timon agenda [today|next] [--json] [--detailed] [--limit N]
timon agenda --from "2026-08-25" --to "+3d" free-form range (ISO, YYYY-MM-DD, now, +2h, +3d)
today = from now to 23:59 local time
next = the next 5, any date

Remote daemon:
timon --daemon <url|name> <cmd> … targets a daemon (URL or profile)
timon daemon add <name> <url> <token> profile in ~/.timon/cli-daemons.json (0600)
timon daemon list profiles (url only, never the token)

env: TIMON_API (default http://localhost:3000)
TIMON_API_TOKEN, otherwise ~/.timon/daemon-token (under $TIMON_HOME)
Raw --daemon URLs only inherit daemon-token for the local listener.
For remote URLs, set TIMON_API_TOKEN or use a named profile.

Additional command usage from source

These blocks supplement the root help (for example pipeline flags). Some commands have no separate usage block. The generator reads them without invoking them.

timon spawn agent input... [--idempotency-key hash]

usage: timon spawn <agent> <input...> [--idempotency-key <hash>]
[--model SLUG] [--backend NAME]
[--extra-skills skill1,skill2] [--extra-mcp mcp1,mcp2]
[--allow "Bash(timon:*),Read(/tmp/*)"]

timon send mission_id input...

usage: timon send <mission_id> <input...>

timon status mission_id

usage: timon status <mission_id>

timon kill mission_id

usage: timon kill <mission_id>

timon wait mission_id [--timeout=120] [--json]

usage: timon wait <mission_id> [--timeout=120] [--json]

timon skill get id

usage: timon skill get <id>

timon skill put id [--file PATH] (or pipe content on stdin)

usage: timon skill put <id> [--file PATH] (or pipe content on stdin)

timon skill rm id

usage: timon skill rm <id>

timon skill list|get|put|rm …

usage: timon skill <list|get|put|rm> …

timon mcp get id

usage: timon mcp get <id>

timon mcp put id [--file PATH] (or pipe JSON on stdin)

usage: timon mcp put <id> [--file PATH] (or pipe JSON on stdin)

timon mcp rm id

usage: timon mcp rm <id>

timon mcp list|get|put|rm …

usage: timon mcp <list|get|put|rm> …

timon agent create name [--prompt-file PATH] [--backend …] [--model …] …

usage: timon agent create <name> [--prompt-file PATH] [--backend …] [--model …] …
(system prompt: pipe on stdin or pass --prompt-file)

timon agent update name [--prompt-file PATH] [--backend …] [--model …] …

usage: timon agent update <name> [--prompt-file PATH] [--backend …] [--model …] …
(everything optional; supply only the fields to change)

timon agent set-scope name NONE|SESSION|AGENT|GLOBAL

usage: timon agent set-scope <name> <NONE|SESSION|AGENT|GLOBAL>

timon agent create|update|set-scope name …

usage: timon agent <create|update|set-scope> <name> …
(deletion is intentionally manual — rm -rf ~/.timon/agents/<name>/)

timon mission summarize mission_id [--force]

usage: timon mission summarize <mission_id> [--force]

timon mission fork mission_id --to agent [--message "..."]

usage: timon mission fork <mission_id> --to <agent> [--message "..."]

timon mission search text… [--agent NAME] [--project SLUG]

usage: timon mission search <text…> [--agent NAME] [--project SLUG]
[--since 7d|ISO] [--until 7d|ISO] [--limit N] [--json]

timon mission summarize|fork|search|reindex …

usage: timon mission <summarize|fork|search|reindex> …

timon task get id

usage: timon task get <id>

timon task create --title TEXT --agent NAME [--description D] [--priority 1-5]

usage: timon task create --title TEXT --agent NAME [--description D] [--priority 1-5]
[--type code|review|merge|research|doc|chore] [--project SLUG] [--base BRANCH]
[--pipeline full|code-self|code-group] [--group-id ID]
[--backend NAME] [--model SLUG] [--permission-mode default|acceptEdits|bypassPermissions]
[--fallback-backend NAME|none] [--fallback-model SLUG]
[--deps id1,id2] [--scheduled ISO] [--extra-skills s1,s2] [--extra-mcp m1,m2]
[--allow "Bash(timon:*),Read(/tmp/*)"]

timon task done id [--comment TEXT | --comment-file PATH | --comment-stdin] [--merged

usage: timon task done <id> [--comment TEXT | --comment-file PATH | --comment-stdin] [--merged-sha SHA]

timon task mark-as-done [id] --comment TEXT | --comment-file PATH | --comment-stdin

usage: timon task mark-as-done [id] --comment TEXT | --comment-file PATH | --comment-stdin
[--verdict pass|changes_requested] [--merged-sha SHA]

timon task mark-as-failed [id] --reason TEXT

usage: timon task mark-as-failed [id] --reason TEXT

timon task block id --reason ...

usage: timon task block <id> --reason ...

timon task update id [--status ...] [--priority N] [--title ...] [--scheduled ISO | -

usage: timon task update <id> [--status ...] [--priority N] [--title ...] [--scheduled ISO | --clear-scheduled]

timon task delete id

usage: timon task delete <id>

timon task list|get|create|done|block|update|delete …

usage: timon task <list|get|create|done|block|update|delete> …

timon series fallback set --scope orchestrator|code|review|merge|doc|chore|*

usage: timon series fallback set --scope orchestrator|code|review|merge|doc|chore|*
--backend NAME [--model SLUG] [--series ID] [--no-apply]
--backend none → this scope does not fall back (failure accepted)
--no-apply → record the rule only, do not move the pending tasks

timon series fallback clear --scope SCOPE [--series ID]

usage: timon series fallback clear --scope SCOPE [--series ID]

timon series fallback list|set|clear …

usage: timon series fallback <list|set|clear> …

timon series role set --scope code|review|merge|research|doc|chore

usage: timon series role set --scope code|review|merge|research|doc|chore
[--backend NAME] [--model SLUG] [--series ID] (at least one of backend/model)

timon series role clear --scope SCOPE [--series ID]

usage: timon series role clear --scope SCOPE [--series ID]

timon series role list|set|clear …

usage: timon series role <list|set|clear> …

timon series fallback|role list|set|clear …

usage: timon series <fallback|role> <list|set|clear> …

timon worktree info task-id

usage: timon worktree info <task-id>

timon worktree create task-id [--base BRANCH]

usage: timon worktree create <task-id> [--base BRANCH]

timon worktree dispose task-id [--force]

usage: timon worktree dispose <task-id> [--force]

timon worktree info|create|dispose task-id …

usage: timon worktree <info|create|dispose> <task-id> …

timon project roles slug

usage: timon project roles <slug>

timon project set-role slug code|review|merge|research|doc|chore agent-name

usage: timon project set-role <slug> <code|review|merge|research|doc|chore> <agent-name>
[--backend NAME] [--model SLUG] [--permission-mode default|acceptEdits|bypassPermissions]
timon project set-role <slug> <role> "" (pour clear)

timon project list|roles|set-role …

usage: timon project <list|roles|set-role> …

timon msg send to_agent payload...

usage: timon msg send <to_agent> <payload...>
[--kind msg|request|response] [--in-reply-to <msg_id>] [--to-mission <mid>]

timon msg pick message_id

usage: timon msg pick <message_id>

timon msg reply message_id payload...

usage: timon msg reply <message_id> <payload...>

timon msg send|recv|pick|reply …

usage: timon msg <send|recv|pick|reply> …

timon pipeline get id

usage: timon pipeline get <id>

timon pipeline create --name TEXT --file PATH [--description D]

usage: timon pipeline create --name TEXT --file PATH [--description D]
(--file points to a JSON file with the pipeline definition: { steps: [...] })

timon pipeline run id [--input JSON | --input-file PATH]

usage: timon pipeline run <id> [--input JSON | --input-file PATH]

timon pipeline run-status run_id

usage: timon pipeline run-status <run_id>

timon pipeline delete id

usage: timon pipeline delete <id>

timon pipeline list|get|create|run|run-status|delete …

usage: timon pipeline <list|get|create|run|run-status|delete> …

timon routine create --name TEXT --agent NAME --cron EXPR --prompt TEXT

usage: timon routine create --name TEXT --agent NAME --cron EXPR --prompt TEXT
[--type code|review|merge|research|doc|chore] [--project SLUG] [--enabled true|false]

timon routine update id [--name ...] [--cron ...] [--enabled true|false] ...

usage: timon routine update <id> [--name ...] [--cron ...] [--enabled true|false] ...

timon routine delete id

usage: timon routine delete <id>

timon routine list|create|update|delete …

usage: timon routine <list|create|update|delete> …

timon project-todo add text... [--project SLUG] [--notes TEXT]

usage: timon project-todo add <text...> [--project SLUG] [--notes TEXT]

timon project-todo update id [text...] [--text TEXT] [--project SLUG] [--notes TEXT]

usage: timon project-todo update <id> [<text...>] [--text TEXT] [--project SLUG] [--notes TEXT] [--status open|done]

timon project-todo done id [--undo]

usage: timon project-todo done <id> [--undo]

timon project-todo promote id --agent NAME [--type TYPE] [--priority N] [--base REF]

usage: timon project-todo promote <id> --agent NAME [--type TYPE] [--priority N] [--base REF] [--pipeline P] [--project SLUG]

timon project-todo rm id

usage: timon project-todo rm <id>

timon project-todo list|add|update|done|promote|rm …

usage: timon project-todo <list|add|update|done|promote|rm> …

timon memory rule add text… [--scope agent|project|role|global] [--agent NAME] [--pro

usage: timon memory rule add <text…> [--scope agent|project|role|global] [--agent NAME] [--project SLUG] [--role ROLE] [--kind pitfall|decision|preference] [--tier normal|core]

timon memory rule rm id

usage: timon memory rule rm <id>

timon memory rule add text… | list | rm id

usage: timon memory rule <add <text…> | list | rm <id>>

timon memory search query…

usage: timon memory search <query…>

timon memory show project|agent id [file]

usage: timon memory show <project|agent> <id> [file]

timon memory rule add|list|rm | search query… | overview | show project|agent id [fil

usage: timon memory <rule <add|list|rm> | search <query…> | overview | show <project|agent> <id> [file]>

timon browser status|start|stop|list [slug] [--json]

usage: timon browser status|start|stop|list [<slug>] [--json]

timon agenda [today|next] [--from X --to Y] [--limit N] [--detailed] [--json]

usage: timon agenda [today|next] [--from X --to Y] [--limit N] [--detailed] [--json]

timon import archive.tar.gz [--to DIR] [--force]

usage: timon import <archive.tar.gz> [--to DIR] [--force]

timon backup enable|status [--json]

usage: timon backup <enable|status> [--json]

timon plugin add spec [--yes]

usage: timon plugin add <spec> [--yes]

timon plugin remove id

usage: timon plugin remove <id>

timon plugin sign dir

usage: timon plugin sign <dir>

timon plugin verify id

usage: timon plugin verify <id>

timon secret set NAME [--scope global|project:slug|agent:name] [--mode inject|broker]

usage: timon secret set <NAME> [--scope global|project:<slug>|agent:<name>] [--mode inject|broker] --stdin

timon secret rm NAME

usage: timon secret rm <NAME>

timon user reset-password email-or-id

usage: timon user reset-password <email-or-id>

timon user invite --email EMAIL --name NAME [--group ID] [--superadmin]

usage: timon user invite --email EMAIL --name NAME [--group ID] [--superadmin]

timon user add-group email-or-id --group ID

usage: timon user add-group <email-or-id> --group ID

timon user remove-group email-or-id --group ID

usage: timon user remove-group <email-or-id> --group ID

timon user groups email-or-id

usage: timon user groups <email-or-id>

timon role list|catalog

usage: timon role list|catalog

timon group set-roles group-id --roles id1,id2,...

usage: timon group set-roles <group-id> --roles id1,id2,...

timon group list|set-roles …

usage: timon group list|set-roles …

timon user list|reset-password|disable|enable|invite|add-group|remove-group|groups …

usage: timon user list|reset-password|disable|enable|invite|add-group|remove-group|groups …

timon secret list|set|grant|revoke|rm|rekey|import-env …

usage: timon secret <list|set|grant|revoke|rm|rekey|import-env> …

timon license install file

usage: timon license install <file>

timon license activate key

usage: timon license activate <key>

timon license status|install file|activate key

usage: timon license status|install <file>|activate <key>

timon trace backfill [--days N]

usage: timon trace backfill [--days N]

timon trace traceId|missionId [--json]

usage: timon trace <traceId|missionId> [--json]

timon daemon add name url token

usage: timon daemon add <name> <url> <token>

timon daemon add nom url token

usage: timon daemon add <nom> <url> <token>
timon daemon list

timon --daemon url|nom commande …

usage: timon --daemon <url|name> <command> …