Skip to content

CLI Reference ​

The clusto binary is the Clusto CLI client. It connects to a clustod daemon over WebSocket and manages Claude Code sessions.

Global Options ​

clusto [OPTIONS] <COMMAND>
OptionEnv VarDefaultDescription
--host <HOST>CLUSTO_HOST127.0.0.1Daemon host address
--port <PORT>CLUSTO_PORT9178Daemon port
--token <TOKEN>CLUSTO_TOKEN(auto*)Authentication token. Prefer CLUSTO_TOKEN or a saved profile: other local users can read a --token value in the process list
--nodes <NODES>CLUSTO_NODES(none)Comma-separated cluster node addresses
--tlsCLUSTO_TLSfalseUse TLS also for a loopback host. Every other host always uses TLS, pinned to the node's identity
--identity <HEX>CLUSTO_IDENTITY(none)Expected node identity (64 hex, from clusto identity show). A node presenting another key is refused before the token is sent
--profile <NAME>CLUSTO_PROFILEthe default profileSaved connection profile (see clusto profile)

Global options go before the subcommand: clusto --token "$T" ls, not clusto ls --token "$T". To avoid putting a token on the command line, export CLUSTO_TOKEN (for the local node, export CLUSTO_TOKEN="$(clusto daemon get-token)") or save a profile.

*The token is optional in most cases. Local-only commands (ps, version, install, update, guide, docs, daemon, cert, profile) never connect to a daemon. For commands that do connect, when --token/CLUSTO_TOKEN is not supplied the CLI uses the active profile's token, then the token stored in the local clustod config (or the access file the daemon writes for its session user, local-daemon.toml in the Clusto config dir) - so commands against the local node work out of the box. The running daemon's access file is read first, then a readable clustod config. A blank CLUSTO_TOKEN or an unexpanded ${CLUSTO_TOKEN} fails with a message naming that cause instead of "invalid token". Supply a token explicitly only when targeting a remote node whose token differs from the local one.

Node identity. On every TLS connection the CLI checks which node it reached before it sends the token. The first time, the node has to prove it holds your token; the CLI then records its identity in known_nodes.toml (next to profiles.toml, keyed by host:port, owner-only). Later connections pin that key, and a node that presents another one is refused before anything is sent, unless it can prove it knows your token (the CLI then prints a warning and re-pins). A plain ws:// connection is used only for a loopback host. See Node Identity & Pairing.

Explicit flags and environment variables override the active profile, which overrides the built-in default of 127.0.0.1:9178. Inside a session the daemon spawned (CLUSTO_DAEMON_SOCKET is set), the default profile is skipped and the CLI connects to that socket (on a TLS daemon this is a plain loopback listener on 127.0.0.1, so an expired certificate does not affect it). An explicit --profile still supplies its token, TLS setting, and node list there, but the session's socket keeps priority over the profile's host and port.

When --nodes is set, the client tries each address once, in order, until one succeeds; it does not follow redirects. Every node is a co-equal authority under leaderless clustering, so any reachable node can serve the request. This overrides --host/--port.

Commands ​

clusto new - Create a session ​

clusto new [OPTIONS]
OptionShortDefaultDescription
--dir <DIR>-d.Working directory for the session
--name <NAME>(none)Optional session name

Creates a new terminal (PTY) session that runs the node's default shell (default_pty_shell), or claude_bin when no default shell is set. The working directory is resolved to an absolute path. Prints the session ID on success. Use clusto open --shell <cmd> to pick the program, clusto attach to watch its output, and the app to type into it.

$ clusto new --dir /home/user/project --name "refactor"
Session created: 550e8400-e29b-41d4-a716-446655440000
  Mode: Pty
  Dir:  /home/user/project
  Name: refactor

clusto ls - List sessions ​

clusto ls

Lists all sessions on the daemon with their ID, mode, attached client count, and working directory.

$ clusto ls
ID                                     MODE     CLIENTS  DIR
550e8400-e29b-41d4-a716-446655440000   pty      0        /home/user/project
6ba7b810-9dad-11d1-80b4-00c04fd430c8   sdk      1        /home/user/other

Mode values: pty (terminal), sdk (headless agent chat), adopted (an external Claude process registered with clusto adopt)

clusto send - Send a prompt ​

clusto send <SESSION> <PROMPT> [--detach]
Argument/OptionDescription
SESSIONSession ID (UUID)
PROMPTThe prompt text to send
--detachReturn as soon as the prompt is queued

Sends a prompt to an SDK-mode (headless agent) session; PTY sessions, including the ones clusto new and clusto open create, do not take it.

Known limitation: the daemon accepts input only from the connection that holds the session's claim, and the CLI never takes one. The daemon therefore rejects the prompt with session is read-only for this connection. Without --detach the CLI reports that error and exits non-zero. With --detach it prints Prompt sent to session <id> (detached). without reading the daemon's reply, so a rejected prompt still looks sent. To hand work to an agent from a shell, use a headless team instead (clusto team create --headless, then clusto team assign and clusto team wait; see clusto team), or type into the session from the app.

clusto attach - Attach to a session ​

clusto attach <SESSION>

Subscribes to an existing session's output stream. Prints all output in real-time until the connection closes, the session completes, or you press Ctrl+C; a daemon error ends it with a non-zero exit. A PTY session prints raw terminal output; an SDK session prints the provider's stream-json lines, one JSON object per line. Attach is read-only: keystrokes are not forwarded.

$ clusto attach 550e8400-e29b-41d4-a716-446655440000
Attached to session 550e8400-e29b-41d4-a716-446655440000. Streaming output...
{"type":"assistant","content":"..."}

clusto kill - Kill a session ​

clusto kill <SESSION>

Terminates the session and its Claude process. The session is removed from the daemon.

$ clusto kill 550e8400-e29b-41d4-a716-446655440000
Session 550e8400-e29b-41d4-a716-446655440000 killed.

clusto tag - Set session tags ​

clusto tag <SESSION> [TAG...]
ArgumentDescription
SESSIONSession ID (UUID)
TAGOne or more tags to set (replaces all existing tags)

Sets tags on a session. All existing tags are replaced by the new list. Pass no tags to clear all tags.

$ clusto tag 550e8400-e29b-41d4-a716-446655440000 backend refactor
Session 550e8400-e29b-41d4-a716-446655440000 tags: backend, refactor

$ clusto tag 550e8400-e29b-41d4-a716-446655440000
Session 550e8400-e29b-41d4-a716-446655440000 tags cleared.

clusto export - Export a session transcript ​

clusto export <SESSION> [--format text|json]
Argument/OptionDescription
SESSIONSession ID (UUID)
--formatOutput format: text (default) or json

Exports a session's full output history with metadata. The text format prints the pre-formatted transcript directly (suitable for piping to a file). The json format emits a JSON object with session_id, filename (suggested save name), and content fields.

$ clusto export 550e8400-e29b-41d4-a716-446655440000 > transcript.txt

$ clusto export 550e8400-e29b-41d4-a716-446655440000 --format json
{"session_id":"550e8400-...","filename":"my-session_2026-03-11.txt","content":"..."}

clusto cluster-status - Show cluster info ​

clusto cluster-status

Displays the cluster topology: this node and all known peers with their connection state. There is no leader or term under leaderless clustering; every node is a co-equal authority.

$ clusto cluster-status
Cluster Status
==============
  Node ID:        a1b2c3d4-e5f6-7890-abcd-ef1234567890 (node-a)

PEER ID                                NAME               ADDRESS                  CONNECTED
b2c3d4e5-f6a7-8901-bcde-f12345678901   node-b             10.0.0.2:9179            yes

A standalone node (no cluster running) prints its configured node ID (all zeros when it has none) and name, followed by No peers.

clusto node controllers - Which nodes may control a node ​

clusto node controllers [--node <ID>] [--set <ID,ID,...> | --any]
OptionDefaultDescription
--node <ID>the connected nodeThe node to read or change (UUID)
--set <ID,ID,...>(none)Allow only these nodes (comma-separated UUIDs). The node itself always may
--anyoffLet every node of the cluster control it again (the default)

--set and --any cannot be combined. Without either, the command prints the node's current list. It reads and writes the node's [cluster] controllers setting, which applies at once. A remote node refuses a list that leaves out the node you are connected to; change that on the node itself. See Who may control a node for what a limited node refuses.

$ clusto node controllers
a1b2c3d4-e5f6-7890-abcd-ef1234567890: every node of the cluster may control it

$ clusto node controllers --set b2c3d4e5-f6a7-8901-bcde-f12345678901
a1b2c3d4-e5f6-7890-abcd-ef1234567890: only these nodes may control it:
  b2c3d4e5-f6a7-8901-bcde-f12345678901

While a limit is set the node refuses the cluster token, so the CLI must use that node's own token.

clusto adopt - Adopt a running Claude process ​

clusto adopt [OPTIONS]
OptionShortDefaultDescription
--pid <PID>-p(none)PID of the Claude process to adopt
--name <NAME>(none)Optional session name
--dir <DIR>-d(none)Working directory for the adopted session

Adopts an already-running Claude Code process into daemon management. Without --pid, discovers running Claude processes and lists them interactively.

The adopted process becomes a managed session (mode: adopted) that can be attached, monitored, and killed like any other session.

$ clusto adopt --pid 12345 --name "existing-work"
Session adopted: 7f3a2b10-...
  PID:  12345
  Mode: Adopted
  Dir:  /home/user/project
  Name: existing-work

clusto open - Open a terminal on the daemon ​

clusto open [OPTIONS]
OptionShortDefaultDescription
--dir <DIR>-d.Working directory for the terminal
--shell <SHELL>-s$SHELL (Unix) or powershell.exe (Windows)Shell or command line to launch (e.g. bash, powershell, cmd, zsh, "pwsh -NoExit")
--name <NAME>(none)Optional human-readable name for this terminal

Opens an interactive shell or command terminal on the daemon. The terminal runs as a managed session that can be attached from other clients.

The working directory is resolved to an absolute path. If --shell is not provided, the command defaults to $SHELL on Unix systems or powershell.exe on Windows.

--shell accepts a whole command line, not just a program name. The daemon first looks the value up in its command registry by name or program path; on a miss it tokenizes the string into a program plus arguments, honouring single quotes, double quotes and backslash escapes. So --shell "claude --dangerously-skip-permissions" and --shell "'/opt/my tools/claude' --flag" both work. A value that names an existing file is used verbatim, so an unquoted path containing spaces is never split. This is a tokenizer, not a shell: &&, pipes and redirection are passed through as literal arguments - wrap them yourself (--shell "bash -lc 'make && ./run'") when you need shell syntax.

The terminal is created and automatically attached - output streams to stdout in real-time. Press Ctrl+C to detach (the terminal continues running on the daemon).

$ clusto open --dir /tmp --shell bash --name "build"
Terminal opened: a1b2c3d4-... (bash)
Attaching... Press Ctrl+C to detach.

The CLI only streams the terminal's output; it does not forward your keystrokes. Type into the terminal from the app. To watch it again later, use clusto attach <session-id>.

clusto team - Manage agent teams ​

clusto team <SUBCOMMAND>

Subcommands for listing and managing agent teams - headless multi-agent orchestration where a leader and its workers each run as a headless claude, codex, opencode, or openrouter agent, one provider and model per member (see Teams). Create a team with clusto team create --name <n> --working-dir <dir> [--agent <provider>] [--model <m>] [--headless] [--project-id <id>] [--permission-mode bypass|accept_edits|plan] and add workers with clusto team spawn-worker <TEAM_ID> [--agent claude|codex|opencode|openrouter] [--model <m>|--tier fast|balanced|deep] [--role <r>]. --agent also accepts copilot, llama, and custom (with --custom-cmd), but only for a leader, which then runs as an interactive terminal; --arg (repeatable) appends extra arguments to the agent command. --headless creates a team with no leader session, so the caller drives the workers itself. The team records where it was created from CLUSTO_CHAT_ID or CLUSTO_SESSION_ID when the command runs inside a chat or a session, which is how the Team tab knows which conversation started it. Teams are persistent: they have no completion state and end only when deleted. --node <NODE_ID> runs the team on another cluster node - use it when --working-dir lives on a machine other than the one you are connected to, since the agents read that node's filesystem and OS accounts. In autopilot, agents coordinate through the clusto-team MCP tools; the subcommands below are the CLI mirror of those tools.

clusto team ls ​

Lists all teams. --json prints the raw team objects.

$ clusto team ls
ID                                     LEADER SESSION       AGENT      STATUS     WORKERS  NAME
a1b2c3d4-...                           550e8400-...         claude     active     3        my-team

clusto team get <TEAM_ID> ​

Shows details for a specific team. --json prints the raw team, including final_result and per-worker worker_results.

$ clusto team get a1b2c3d4-e5f6-7890-abcd-ef1234567890
Team:    a1b2c3d4-...
Name:    my-team
Status:  Active
Leader:  550e8400-... [claude]
Workers: 3
  - 6ba7b810-... [claude]
  - 7c8d9e0f-... [codex]
  - 8d9e0f1a-... [opencode]

clusto team delete <TEAM_ID> ​

Deletes a team and kills all its sessions.

$ clusto team delete a1b2c3d4-e5f6-7890-abcd-ef1234567890
Team a1b2c3d4-... deleted.

Autopilot subcommands ​

A headless leader normally orchestrates workers through the clusto-team MCP tools (see Teams Autopilot); these subcommands mirror those tools for shell scripts, humans, and non-Claude (PTY) leaders:

CommandPurpose
clusto team handoff <TEAM_ID> --prompt <p> [--name <n>] [--working-dir <d>] [--agent <provider>] [--model <m>|--tier fast|balanced|deep] [--role <r>] [--timeout <secs>]Spawn worker + block until report (default 60 s, max 3600). Prints a wait_id on timeout.
clusto team assign <TEAM_ID> --prompt <p> [--name <n>] [--working-dir <d>] [--agent <provider>] [--model <m>|--tier <t>] [--role <r>]Spawn worker and return immediately (queued when the team is at capacity). Pair with wait.
clusto team send <TEAM_ID> [--to <id> | --broadcast] --message <m> [--from <id>]DM a worker or broadcast to the team.
clusto team inbox <TEAM_ID> [--session <id>] [--since <seq>] [--watch]Replay relayed messages (NDJSON). At-least-once on seq.
clusto team workers <TEAM_ID> [--json]Print the roster with per-worker status (pending, reported(success|failure|unknown), exited(unverified)).
clusto team roster <TEAM_ID> [--json]Live roster: each member's state, context use, branch and result, plus queued assignments.
clusto team merge <TEAM_ID> [--worker <id>]... [--target-branch <b>] [--apply]Preview, or with --apply perform, merges of worker branches into the checked-out branch.
clusto team report <TEAM_ID> --success|--failure [--result <s>] [--session <id>]Worker reports its result.
clusto team summary <TEAM_ID> [--result <s>]Leader publishes a progress summary. Teams are persistent - this does not end the team.
clusto team refresh-context <TEAM_ID> [--carryover <note>]Restart the leader's conversation with an empty context, seeded by the carryover note.
clusto team models [--provider <p>] [--refresh] [--node <uuid>] [--json]List the models a node offers per agent CLI (the connected node, or --node), with tier and the recommended pick.
clusto team wait <TEAM_ID> [--for <ids>] [--timeout <secs>] [--wait-id <id>]Bounded block on pending workers (default 60 s, max 3600).
clusto team statusPrint env-derived identity (CLUSTO_TEAM_ID, CLUSTO_SESSION_ID, role) and team summary.

Workers spawned via handoff/assign default to an isolated git worktree under .clusto/worktrees/<worker-id> (or a plain sandbox dir if the leader cwd is not a git repo). At most 5 workers may be active without a recorded result; completed workers remain in the roster but no longer consume capacity. The Claude Stop hook reports a worker that exits without calling team report, but it can only mark it failed or unverified, never successful.

clusto team mcp runs the stdio MCP server that exposes these operations as mcp__clusto-team__* tools. The daemon wires it into each headless agent (with --mcp-config for Claude, config overrides for Codex and OpenCode; native OpenRouter agents call the team CLI through their command tool); it is not meant to be run by hand. New team members require this CLI to report the same version as clustod and pass the daemon's team mcp capability check.

clusto internal stop - Stop-hook helper (not for direct use) ​

Called by the Claude Stop hook in .claude/settings.json that the autopilot skill materialises. Reads CLUSTO_TEAM_ID / CLUSTO_SESSION_ID from the env, extracts the last assistant message from --transcript or the hook payload's transcript_path on stdin, and emits ReportWorkerResult to the daemon.

clusto internal stop [--team-id <id>] [--session-id <id>] [--transcript <path>] [--failure]

clusto internal notify-state --waiting|--idle is the sibling hook helper that drives the waiting-for-input marker; see Agent Waiting Marker. clusto internal name-session --name <name> [--session-id <id>] renames the current session (default $CLUSTO_SESSION_ID) from an in-session agent helper.

clusto logs and clusto clients - Diagnostics ​

clusto logs daemon [--lines <N>] [--node <NODE_ID>]
clusto logs app --client <CONNECTION_ID> [--lines <N>]
clusto logs frontend --client <CONNECTION_ID> [--lines <N>]
clusto clients ls

clusto logs daemon prints the connected daemon's log, or with --node a cluster peer's. app and frontend fetch a connected app's Rust-side log or its WebView diagnostics buffer; clusto clients ls lists the connection IDs to pass as --client, followed by the cluster nodes. --lines defaults to 500 (1500 for frontend). See Remote Log Fetch.

clusto guide - Manual for AI assistants ​

clusto guide [setup|sessions|teams|tasks|reports|projects|mcp|all]

Prints a short, command-first manual written for an AI agent that drives Clusto from a shell. Without a topic it prints the index; each topic is a few KB so an agent can load only what it needs, and all prints everything for piping into a context window. The text ships inside the binary, so it always matches the installed version and works offline. Does not require a daemon connection or token.

TopicCovers
setupConnection order (flags, env vars, profile), tokens, TLS, clusters
sessionsDelegating to a session without streaming its transcript
teamsHeadless and led teams, workers, wait, merge
tasksCreating scheduled tasks, cron syntax, injected run variables
reportsclusto report and the report MCP tools
projectsclusto project, clusto file, clusto git
mcpInstalling clusto report mcp into Claude Code, Codex and other MCP clients

To teach an agent Clusto, tell it: "You have the clusto CLI. Run clusto guide to learn it." clusto --help points there too.

clusto docs - Read the user documentation ​

clusto docs list
clusto docs search <words> [--limit N]
clusto docs read <page> [--section <heading>]

The full Clusto user documentation, the same pages published at clusto.app/docs, is embedded in the CLI. Like clusto guide, it matches the installed version, works offline, and does not require a daemon connection or token.

SubcommandDoes
listLists every page slug with its one-line description
search <words>Prints the best matching sections with a short snippet. --limit caps the results (default 8)
read <page>Prints a page by slug, as list shows it. --section prints only the section whose heading matches
bash
clusto docs search openrouter api key
clusto docs read reports --section "Automatic failure notices"

The Clusto Assistant answers from these pages, and any agent with a shell can use the same commands. clusto guide points to clusto docs for anything beyond its command-first topics.

clusto mcp - Knowledge MCP server ​

clusto mcp

Serves the Knowledge MCP tools over stdio: approved lessons, lesson proposals, Notes vaults, scheduled tasks, time tracking, the Factory, reports, GitHub and Azure DevOps views, the docs and the cluster. Every tool is listed in Knowledge. Clusto registers it as the clusto MCP server in Claude Code, Codex, and Gemini CLI on every node, so you rarely run it by hand. It reaches the local daemon through the access file the daemon writes (~/.config/clusto/local-daemon.toml), so no flags or token are needed. See Knowledge.

clusto plugin - Manage user plugins ​

clusto plugin ls
clusto plugin inspect <SOURCE> [--ref <REF>]
clusto plugin install <SOURCE> [--ref <REF>] [--on <NODE_IDS>] [--run-as <USER>] [--yes]
clusto plugin update <ID> [--ref <REF>] [--yes]
clusto plugin rm <ID>
clusto plugin enable <ID>
clusto plugin disable <ID>
clusto plugin status [--node <NODE_ID>]
clusto plugin logs <ID> [--node <NODE_ID>]
clusto plugin view <ID> <VIEW> [--node <NODE_ID>] [--param <KEY=VALUE>]
clusto plugin run <ID> <COMMAND> [--node <NODE_ID>] [--project <ID>] [--session <ID>]

Manages plugins.

SubcommandWhat it does
lsList installed plugins
inspectShow what a git URL or folder on the connected node would add, without installing it. --ref picks a branch, tag or commit
installInstall from a git URL or folder. Prints what the plugin adds and asks before saving. --on limits the install to a comma-separated list of node ids (default: every node), --run-as sets the OS account its processes run as (default: the node's default_session_user), --yes skips the prompt
updateMove a git plugin to a new commit, or re-read a folder plugin's manifest. --ref picks the branch, tag or commit
rmUninstall from every node
enable, disableTurn a plugin on or off without uninstalling it
statusInstall state of every plugin on a node (default: the connected node)
logsTail of a plugin's log on a node
viewRender a plugin view and print the reply as JSON. --param key=value can be repeated
runRun a background plugin command and print its output. --project and --session set the target

Plugins run native code with the permissions of their run-as account, so install only plugins you trust. See Plugins for the manifest and examples.

clusto chat mcp - Chat tools MCP server (not for direct use) ​

Serves chat controls and attached cross-node context over stdio, plus the Clusto Assistant tools in assistant chats. The daemon spawns it for native chats; it is not meant to be run by hand.

clusto doctor - Check this node's daemon install, cluster and AI setup ​

clusto doctor [--fix]

Checks the local daemon install first, then the cluster as this node sees it, then this node's AI setup. It does not need a daemon connection to run the install checks.

Daemon install. It inspects the clustod service and the legacy hived service (state, program path, and --config), any Hive-era state on disk, and the Hive to Clusto cutover journal (C:\ProgramData\Clusto\migration on Windows, /var/lib/clusto-migration on Linux; reading it needs an Administrator terminal or sudo). It prints [mark] label - detail lines and one diagnosis:

DiagnosisMeaning
Not installedNo daemon found. Run clusto install
clustod runningHealthy. An old hived service may stay registered but disabled during the rollback window; that is normal
clustod stoppedThe service is installed but not running
Both running (conflict)hived and clustod are active at the same time
Cutover in progressThe journaled Hive to Clusto cutover has started and not finished. Check again in a minute
Cutover stopped part-wayThe cutover started but will not finish on its own: hived runs again, or the journal has not changed for 10 minutes. Shows the journal phase and its last error
Cutover rolled backThe cutover failed and was undone. Shows the target version and the recorded error. Each newer daemon version retries once
Stale hived registrationA hived service is registered but its program is gone
Hive-era node stopped / runningAn old hived node that has not moved to clustod yet
Hive data with no daemonHive state exists but no daemon does. Clusto never touches it automatically; move it away yourself if you want a fresh install

Cluster. Next it lists how many peers are connected and flags:

MarkFindingRepair with --fix
FAILA peer presents a new identity, so every link to it is refused (shows both fingerprints)Trust the new identity, the same as Trust new identity in the app
WARNA stale entry: an offline peer whose host now runs another, connected node (left over from a reinstall or re-adoption)Remove the stale entry from the cluster
WARNA leftover address: a roster address that no known node owns and no node answers at, such as the hostname of a retired build server. Every node keeps dialing it. Printed as <address> is in the cluster roster but no known node answers there ...Remove the address from every node's roster (needs the admin token)
WARNA connected peer runs another Clusto version. Mixed versions are not supported and can break terminals and chatsUpdate every outdated node to the latest release; each restarts, and its live terminal sessions end unless they were started with the terminal.survive_restart flag on

Each cluster repair changes what the whole cluster accepts, so --fix asks [y/N] before each one and never repairs without a terminal. Only trust a new identity for a node you reinstalled or reset yourself (see troubleshooting). For a leftover address, --fix asks Remove <address> from every node's roster? [y/N]. The removal is remembered and gossiped with the cluster config, so a node that was offline drops the address when it reconnects and no peer can sync it back. An address a known node holds, or one with a live link, is refused: remove that node instead. If the daemon cannot be reached, this part prints Cluster: not checked - <reason>.

AI setup. Then it shows MCP registration per tool, the managed instruction section, memory sync, and backups. If the daemon cannot be reached, this part prints AI setup: not checked - <reason> instead of failing. Leftover Hive paths print as Hive program (an old hived binary) or Hive state (config and data).

Terminal holders. On Linux, when any terminal holders are running, it prints a Terminal holders: N running line.

--fix repairs what it can. Run it from an Administrator terminal on Windows or with sudo on Linux. The AI setup repair needs the node admin token: inside a session that holds a limited session credential, --fix shows the AI setup checks without repairing them and says so; use Fix now in the app or pass --token. The install repairs:

  • starts a stopped clustod;
  • stops and disables a running hived that sits next to clustod;
  • for a Hive-era node, starts hived, updates it to the current release through the normal node self-update, and waits up to 5 minutes for the daemon's own journaled cutover to replace hived with clustod. Data, token and sessions are kept. If the cutover does not happen, it prints the daemon's own blocker reason;
  • for a Hive-era node whose cutover journal already holds a rollback backup (the cutover was prepared, or rolled back), installs the daemon program this clusto bundles in place of hived, restarts it, and waits for the cutover. It refuses to replace a node that runs a newer version than the CLI;
  • for a cutover that stopped part-way (hived runs again, or the journal has not moved for 10 minutes), rolls it back with the bundled daemon, which returns the node to hived, then installs the bundled daemon and lets the cutover run again;
  • removes a stale hived service registration, and a stopped clustod registration that a rolled-back cutover left behind;
  • re-runs the AI setup.

See Moving from Hive to Clusto.

clusto lessons - Review agent lessons ​

clusto lessons pending
clusto lessons approve <id> [--global]
clusto lessons drop <id>
clusto lessons list [--repo <path>]
clusto lessons propose <title> <body> [--repo <path>]
SubcommandDoes
pendingLessons agents proposed that wait for your review
approve <id>Approves a proposal for its repository, or everywhere with --global
drop <id>Drops a proposed or approved lesson
listApproved lessons for a repository (default: the current directory)
proposeProposes a lesson yourself

A proposal has no effect until it is approved. See Knowledge.

clusto notes, clusto time and clusto tool - Tools from a shell ​

clusto notes vaults
clusto notes ls [--vault <VAULT>]
clusto notes search <QUERY> [--vault <VAULT>]
clusto notes read <PATH> [--vault <VAULT>]
clusto notes write <PATH> [--content <TEXT> | --file <PATH>] [--base-sha256 <SHA256>] [--vault <VAULT>]
clusto notes mv <FROM> <TO> [--vault <VAULT>]
clusto notes rm <PATH> [--vault <VAULT>]

clusto time status
clusto time start [DESCRIPTION] [--project <PROJECT>] [--tag <TAG>]...
clusto time stop [--entry <ENTRY_ID>]
clusto time ls [--from <FROM>] [--to <TO>]
clusto time add [DESCRIPTION] --start <START> [--end <END> | --minutes <N>] [--project <PROJECT>] [--tag <TAG>]...
clusto time edit <ENTRY_ID> [--description <TEXT>] [--start <START>] [--end <END> | --minutes <N>] [--project <PROJECT>] [--tag <TAG>]... [--no-tags]
clusto time rm <ENTRY_ID>
clusto time project add <NAME> [--client <CLIENT>] [--color <COLOR>]
clusto time project edit <PROJECT> [--name <NAME>] [--client <CLIENT>] [--color <COLOR>] [--archive | --unarchive]
clusto time project rm <PROJECT>

clusto tool ls [--json]
clusto tool call <NAME> [JSON_ARGS]

These run the clusto mcp tools from a shell, through the same code an agent uses, so the same checks apply. They reach the local daemon through its access file, like clusto lessons.

CommandDoes
notes vaults, ls, search, readList the vaults, list a vault, search it, and print one note with its SHA-256
notes writeCreates or updates a note. The text comes from --content, --file or standard input. Updating an existing note needs --base-sha256 from notes read
notes mv, notes rmMove or rename a note or folder (never overwrites), and delete a note or an empty folder
time status, start, stop, lsThe running timer and today's entries, start and stop the timer, and list entries (default: the last 7 days)
time add, edit, rmBook a finished entry with explicit times, change one (omitted options keep their value, --project "" removes the project), delete one
time project add, edit, rmCreate, rename, recolor, archive or delete a time project. Its entries stay, without a project, when it is deleted
tool lsLists every tool clusto mcp serves; --json prints the full definitions
tool call <NAME> '<JSON>'Runs one tool by name with JSON arguments

Times are RFC 3339 (2026-11-09T09:00:00+01:00), or without an offset in this machine's time zone (2026-11-09T09:00).

bash
clusto time add "standup" --start 2026-11-09T09:00 --minutes 30 --project Clusto
clusto tool call clusto_github_prs '{}'

See Knowledge and Time tracking.

clusto ps - List local Claude processes ​

clusto ps

Lists Claude Code processes running on the local machine. Does not require a daemon connection or token.

$ clusto ps
PID      WORKING DIR                    COMMAND
--------------------------------------------------------------------------------
12345    /home/user/project             claude --print --output-format stream-json ...
67890    ...ser/very/long/project/path  claude

clusto version - Show version information ​

clusto version

Prints the version of this CLI binary, its build platform, and the version of the locally installed clustod daemon (if one is installed). Does not require a daemon connection or token. clusto --version (and -V) print the CLI version alone.

$ clusto version
clusto (CLI):  v1.14.41
platform:      linux-x64
clustod (local): clustod 1.14.41

clusto install - Install the daemon ​

clusto install [OPTIONS]
OptionDefaultDescription
--non-interactivefalseSkip interactive prompts, use defaults
--name <NAME>(none)Node display name (skips name prompt)
--port <PORT>9178Daemon listen port (skips port prompt)
--bind <ADDR>0.0.0.0Bind address (skips bind address prompt)
--user-secret <SECRET>(none)Custom pairing password (16 or more characters, reusable, no expiry). Only a verifier is written to the daemon config, never the password. The flag keeps its old name; the password lands in the process list, so prefer --pairing-code or clusto pairing set
--pairing-codefalseCreate a single-use pairing code that expires in 24 hours, without prompting, and print it with its pairing link at the end. Cannot be combined with --user-secret
--pairing-code-file <PATH>(none)Use the pairing code in that file instead of generating one (single use, expires in 24 hours), then delete the file. The code is not printed. Conflicts with --user-secret and --pairing-code. The desktop app uses it for one-click setup
--userfalseInstall for the current account only, without root or Windows administrator rights. See Install without sudo. Do not run it under sudo
--reinstallfalseReplace the config of a machine that already has clustod. Needed for non-interactive runs; the wizard otherwise asks first
--jsonfalsePrint a single JSON summary line for a script to parse (it includes "user_install": true|false). The daemon is not started in this mode. It never repairs a Hive-era node and fails with the diagnosis instead

Extracts the bundled clustod daemon binary and runs a configuration wizard. The wizard offers to start the daemon when setup finishes and defaults to yes. On Linux, it prefers the installed systemd service when available. This command does not require a daemon connection or token.

Never a second daemon. Before it writes anything, clusto install checks for an existing daemon, the same way clusto doctor does:

  • On a Hive-era node (a hived service or Hive state) it prints the doctor diagnosis and offers the in-place upgrade: Repair the existing node now? [Y/n]. Answering yes does what clusto doctor --fix does and keeps the data, token and sessions. --non-interactive repairs without asking. With --json it never repairs and fails with the diagnosis.
  • On a machine that already has clustod, it asks Reinstall and replace its config? ... [y/N]. The default is no, because the wizard writes a new token and resets the cluster settings. A non-interactive run needs --reinstall.

The wizard prompts for: display name, port, bind address, token (blank auto-generates one), whether to create a pairing code, default working directory, optional cluster settings, and the install directory. The claude binary is detected, not prompted for. The config is written to the platform config directory. On Linux the installer also writes and enables the clustod systemd unit when it can write /etc/systemd/system.

Windows. Run the command from an Administrator terminal, or use the one-line installer, which elevates for you:

powershell
irm https://dl.clusto.app/install.ps1 | iex

The installer stops a running clustod service so the binary can be replaced, registers clustod as a Windows service that starts automatically at boot and restarts after a crash, points it at the config in your profile (%APPDATA%\vazac\Clusto\config\config.toml), and adds an inbound Windows Firewall rule for clustod.exe so peers and clients can reach it. Every connection still has to authenticate with the token.

Install without sudo or administrator rights. clusto install --user installs the daemon for the current account only. Nothing is written outside your home directory and no root or UAC prompt is needed.

LinuxmacOSWindows
Install dir~/.local/bin~/.local/bin%LOCALAPPDATA%\Programs\Clusto
Config~/.config/clusto/config.tomlper-user configper-user config
Autostartsystemd user unit ~/.config/systemd/user/clustod.service (Restart=always), enabled, plus loginctl enable-lingerLaunchAgent ~/Library/LaunchAgents/app.clusto.clustod.plist (RunAtLoad, KeepAlive), loaded with launchctl bootstrap gui/<uid>Clusto Daemon value under HKCU\Software\Microsoft\Windows\CurrentVersion\Run, starts at sign-in
  • On Windows there is no service, no clusto-runas helper and no firewall rule; Windows may show its own firewall prompt the first time the daemon listens.
  • If the user manager is not reachable (for example no login session), the installer says so and starts the daemon detached. It then does not come back after a reboot; re-run the install from a login session.
  • Sessions and chats run as that account only; there is no run-as for other OS users.
  • A machine has either a system install or a user install, never both. clusto install --user refuses when a system clustod exists, and a plain clusto install refuses when a user install exists (remove it first with systemctl --user disable --now clustod).
  • Self-update, restart and surviving terminals work under the user manager. The system-only /etc drop-ins (priority hardening, holder slice, tailscaled weight) are skipped.
  • On Linux, clusto doctor shows the unit as "clustod user service".

Resolving the claude binary. The installer resolves the configured claude command to an absolute path so the daemon does not depend on its own PATH at runtime. Beyond a plain PATH lookup it also probes the sudo-invoking user's ~/.local/bin/claude and ~/.npm-global/bin/claude, since Claude Code is commonly installed there for the human user rather than root. When no claude is found anywhere, the install still completes but prints a warning so you can set claude_bin by hand later.

Client config for sudo installs. The daemon config lives under the root/service user (for example /root/.config/clusto/...). When clusto install runs via sudo, it also writes a minimal client connect config to the invoking user's ~/.config/clusto/config.toml - just display_name, bind, port, and token - owned by that user with 0600 permissions. An existing user config is never overwritten. The CLI reads it when that user runs clusto: it is the local token fallback for connected commands and what clusto daemon get-token prints without sudo.

The app does not read this file or automatically create a local connection. Add the daemon's host, port, and token under Connection, or use desktop Scan Network to find the installed daemon and supply its token. Previously saved local connection profiles continue to work.

Default install paths (the interactive wizard lets you change the directory):

  • Windows: C:\Program Files\Clusto\clustod.exe (the installer asks for administrator rights through UAC when it needs them)
  • Linux/macOS: /usr/local/bin/clustod
$ sudo clusto install
Clusto Daemon Installer
==============================
...
Found claude CLI: /home/alice/.local/bin/claude
Installing daemon binary to /usr/local/bin/clustod...
Writing config to /root/.config/clusto/config.toml...
Wrote client connect config to /home/alice/.config/clusto/config.toml
Wrote systemd unit to /etc/systemd/system/clustod.service
  Enabled clustod to start on boot
Daemon started (systemd unit clustod.service).

Done!
  Node name:  my-node
  Address:    0.0.0.0:9178
  Token:      a3f8b2c1d4e5...
  Binary:     /usr/local/bin/clustod
  Config:     /root/.config/clusto/config.toml

clusto rename-node - Rename a cluster node ​

clusto rename-node <NODE_ID> <NAME>
ArgumentDescription
NODE_IDNode UUID (from clusto cluster-status)
NAMENew display name for the node. An empty string ("") clears it

Renames a cluster node. The name is saved to the node's config file and propagated to all peers immediately. Clearing the name removes it from the config; the node then shows its short id, and its hostname after the next daemon restart.

$ clusto rename-node a1b2c3d4-e5f6-7890-abcd-ef1234567890 "production-1"
Node renamed.

clusto update - Update the CLI ​

clusto update [OPTIONS]
OptionDefaultDescription
--from <URL>local node's [update].manifest_url, else https://clusto.app/Remote manifest base URL
--channel <CHANNEL>(ignored)Hidden, deprecated: prints a notice that channels are gone and is ignored; removed after one release
--remote-token <TOKEN>$CLUSTO_UPDATE_TOKEN, else local node's [update].tokenBearer token for private remote manifests
--version <X.Y.Z>newest releaseInstall this exact release from its per-version manifest; only the 10 most recent releases stay published
--dry-runfalseVerify the manifest and report what an update would do, without downloading or changing anything

Updates the running clusto CLI binary in place. This is a local-only command - it does not connect to a daemon.

By default the CLI reads the local clustod config's [update] section and follows the same manifest URL the node itself tracks; no flags needed. --from and --remote-token override the config values. The manifest is manifest.json in that directory; a --from URL whose last segment ends in .json is used as the manifest itself. There are no release channels any more. The binary is verified by SHA-256 before the running CLI is replaced and restarted.

Examples:

bash
# Follow the local node's configured manifest URL
clusto update

# Pull the CLI directly from a specific remote manifest base URL
clusto update --from https://updates.example.com/clusto/

# Private manifest
CLUSTO_UPDATE_TOKEN=secret clusto update --from https://updates.example.com/clusto/

# Install release 1.15.29 instead of the newest one
clusto update --version 1.15.29

--version reads manifest-<X.Y.Z>.json next to the manifest it would otherwise use. A release older than the running CLI is still refused, and a release outside the 10 most recent fails with release vX is not published (only the 10 most recent releases stay installable). See Installing a specific release.

clusto update-node - Update a node from a URL ​

clusto update-node [OPTIONS]
OptionDefaultDescription
--from <URL>local node's [update].manifest_url, else https://clusto.app/Remote manifest base URL
--channel <CHANNEL>(ignored)Hidden, deprecated: prints a notice that channels are gone and is ignored; removed after one release
--remote-token <TOKEN>$CLUSTO_UPDATE_TOKEN, else local node's [update].tokenBearer token for private remote manifests
--refresh-artifactsfalseAlso refresh remaining artifacts for other platforms and app clients
--version <X.Y.Z>newest releaseInstall this exact release from its per-version manifest; only the 10 most recent releases stay published
--clusterfalseUpdate every outdated node of the cluster in one run (staged together, one restart)
--match-node <NAME>With --cluster: roll out the release the named node runs (display name or node id). Cannot be combined with --version
--dry-runfalseVerify the target manifest and list what each node would do, without asking any node to update

Asks the connected node to fetch a remote manifest, download the daemon and CLI binaries for its own platform, verify both, stage them, install or update the CLI, and restart the daemon. A missing or invalid same-platform CLI artifact fails the update before the restart begins. If the staged CLI cannot be copied, made executable, or renamed into place on the next boot, daemon startup fails instead of running with a missing or stale CLI.

With no arguments this updates the local node (the daemon on --host, which defaults to 127.0.0.1), following the same [update] manifest URL the node already tracks - mirroring how clusto update self-updates the CLI. So a plain clusto update-node is all you need to bring the local daemon and CLI up to date. --from and --remote-token override the config values.

The daemon restart ends the node's live terminal sessions, except those running in a holder process, which is the default (see Terminals that survive a restart).

The current node's CLI is always refreshed. Use --refresh-artifacts when you also want the daemon to stage the remaining manifest entries, including CLIs and daemons for other platforms, desktop app installers, and Android APKs.

bash
# Update the local node, following its configured manifest URL
clusto update-node

# Update a specific node from an explicit manifest URL
clusto --host node2.example.com update-node --from https://updates.example.com/clusto/
clusto update-node --from https://updates.example.com/clusto/ --refresh-artifacts

# Bring the whole cluster to the release you tested on home-pc
clusto update-node --cluster --match-node home-pc --dry-run
clusto update-node --cluster --match-node home-pc

# Or name the release
clusto update-node --cluster --version 1.15.29

Nodes already ahead of the target are never downgraded: the CLI lists them as Left alone and the daemon skips them. --cluster without --version or --match-node updates every outdated node to the newest release. See Installing a specific release.

The previous name clusto update-daemon still works as an alias.

clusto discover - Discover Clusto nodes on Tailscale ​

clusto discover

Asks the connected daemon to scan its Tailscale network for other Clusto nodes, then prints each discovered host with its address, hostname, whether it is reachable, whether it runs clustod, its version, and its display name. The scan identifies TLS-only nodes (those that serve wss:// and reject plain ws://) too. This command needs a daemon connection like any other.

$ clusto discover
ADDRESS                  HOSTNAME             REACHABLE  CLUSTOD  VERSION    NAME
100.64.1.2:9178          pi                   yes        yes      1.14.41    vazypi
100.64.1.3:9178          desktop              yes        yes      1.14.41    workstation

clusto daemon - Local daemon management ​

clusto daemon <SUBCOMMAND>

Subcommands for inspecting the locally installed daemon. All but link read the local config file directly and do not require a daemon connection.

clusto daemon get-token ​

Prints the credential this account holds for the local daemon. It reads the running daemon's access file (local-daemon.toml in the Clusto config dir) first, then a readable clustod config. For an account other than the daemon's, the access file holds a limited session credential, so get-token prints that credential, which cannot run admin commands, and adds a note on stderr saying so. Run it with sudo (or read the daemon's config.toml; on Windows that is the config path clusto doctor shows for the clustod service) to get the node admin token.

$ clusto daemon get-token
a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5...

clusto daemon get-config ​

Prints the daemon config file as it is on disk.

$ clusto daemon get-config
bind = "0.0.0.0"
port = 9178
token = "..."
display_name = "my-node"
...

clusto daemon status ​

Shows whether the daemon is installed, its binary path and version, the config path, and whether it is currently running.

$ clusto daemon status
Installed:    yes
Binary:       /usr/local/bin/clustod
Version:      clustod 1.14.41
Config:       /root/.config/clusto/config.toml
Running:      yes
clusto daemon link [--node <UUID>] [--cloud <URL>]

Links a node to your Clusto account so the web relay will reach it. This is the one daemon subcommand that connects to a daemon: it asks the node to sign a short statement with its tunnel key and prints a URL, https://clusto.app/account/link-node#claim=.... Open it within 10 minutes in a browser where you are signed in, and confirm. A signed-in Clusto app links nodes on its own; use this for a node only the relay can reach.

OptionDescription
--node <UUID>Sign for another node of the cluster instead of the connected one
--cloud <URL>Cloud site to link with (default https://clusto.app). Must be https, or http for a loopback host

It needs the node admin token (--token, CLUSTO_TOKEN, a profile, or the local daemon config), so on the root service run it with sudo. The URL is a bearer capability until it expires: treat it like a password. The node needs its tunnel enabled.

These commands read the config of the OS user running them. The packaged Linux service runs as root, so run them with sudo there.

clusto profile - Saved connection profiles ​

clusto profile add <NAME> [--host <HOST>] [--port <PORT>] [--token <TOKEN>] [--tls] [--nodes <NODES>]
clusto profile list
clusto profile show [NAME]
clusto profile use <NAME>
clusto profile remove <NAME>

A profile stores host, port, token, TLS, and cluster node settings under a name, so you do not pass connection flags on every command. Profiles live in profiles.toml in the Clusto config directory (~/.config/clusto/profiles.toml on Linux), written owner-only because they hold tokens. This command is local-only.

SubcommandDoes
addAdds a profile, or updates the given fields of an existing one. The first profile becomes the default
list (ls)Lists saved profiles and marks the default
showPrints a profile (default: the default profile) with the token masked
useMakes a profile the default
remove (rm)Deletes a profile

The active profile is the one named by --profile or CLUSTO_PROFILE, else the default (skipped inside a Clusto session, see Global Options). Its values fill in whatever flags and environment variables leave unset. An unknown profile name is an error, and so is a profiles.toml that cannot be read or parsed: connected commands stop instead of falling back to the local daemon, and the profile subcommands refuse to overwrite the file.

bash
clusto profile add home --host 100.64.0.10 --port 9178 --token <token>
clusto profile use home
clusto ls                      # connects with the home profile
clusto --profile work ls       # one-off override

clusto pairing - Pairing codes ​

clusto pairing generate [--expires <30m|24h|7d|never>] [--reusable]
clusto pairing set [--expires <30m|24h|7d|never>] [--single-use]
clusto pairing status
clusto pairing clear

Manages the pairing code or password of the connected node (add --host or a profile to target another one). A pairing code lets the app, or another node, take over this node without copying its token. Whoever uses a code gets full control of the node and the cluster. See Node Identity & Pairing. These commands need the node admin token.

SubcommandDoes
generateCreates a code (XXXXX-XXXXX-XXXXX-XXXXX) and prints it once with its pairing link and expiry. Defaults to single use and 24 hours; --reusable keeps it valid after the first use
setSets a custom password of 16 to 256 characters. Read from the terminal (hidden, typed twice) or one line of stdin when piped, never from the command line. Defaults to reusable and no expiry
statusShows whether pairing is active, its kind, whether it is single use and when it expires, or that it is expired, locked or "reset required". Never the code
clearRemoves the code or password. Pairing is then disabled

Setting a new code or password also clears a pairing lockout. status is the quickest way to see why a code is refused.

$ clusto pairing generate --expires 7d
Pairing code: 7K2QD-X9M4T-HV8PB-3WNRC
Pairing link: clusto://pair?v=1&node=...&id=...&addr=10.0.0.1%3A9178&code=7K2QD...
Expires: 2026-10-16 09:00 (in 7 days, single use)
Whoever uses this code gets full control of this node and the cluster.

clusto identity - Node identities ​

clusto identity show
clusto identity list
clusto identity forget <HOST:PORT>
SubcommandDoes
showPrints the connected node's identity (64 hex), its fingerprint (abcd-ef01-2345-6789) and its node id. Use the identity with --identity to pin a node you reached over another channel
list (ls)Lists the identities this CLI has verified and remembers in known_nodes.toml. Local only
forgetDrops the recorded identity of one node, as dialed (host:port), so the next connection verifies it again with your token. Use it after you reinstalled a node on purpose. Local only

See Node Identity & Pairing for what happens when a node's identity changes.

clusto cert - Provision TLS for the web client ​

clusto cert [OPTIONS]

A browser served over HTTPS cannot open a plain ws:// socket to a remote host, and cannot pin a node's identity key, so the web client connects directly only to nodes that serve a browser certificate (wss://). The desktop and mobile apps and the CLI need no certificate. This command makes that one step: it detects the node's Tailscale MagicDNS name (<node>.<tailnet>.ts.net), issues a browser-trusted certificate with tailscale cert, writes it next to the daemon config, sets tls_cert/tls_key, and (with --restart) restarts the daemon.

OptionDescription
--name <NAME>Domain to issue the cert for. Defaults to this machine's Tailscale MagicDNS name.
--restartRestart clustod after writing the config (systemd hosts only).
--config <PATH>Daemon config file to update. Defaults to the per-user config dir; pass this when clustod runs with --config <path> (e.g. a system install at /etc/clusto/config.toml). The daemon also passes its own config path automatically when it invokes clusto cert.

Run it on the machine the daemon runs on (usually with sudo, since tailscale cert and the config write need privileges):

$ sudo clusto cert --restart
Provisioning a TLS certificate for: my-node.tailnet.ts.net
Wrote certificate: /root/.config/clusto/tls/my-node.tailnet.ts.net.crt
Wrote private key: /root/.config/clusto/tls/my-node.tailnet.ts.net.key
Updated /root/.config/clusto/config.toml (tls_cert / tls_key set).
Restarting clustod (systemctl restart clustod)...
clustod restarted.

Requirements: the Tailscale CLI on PATH (override with CLUSTO_TAILSCALE_BIN) and HTTPS Certificates enabled for the tailnet. clusto cert fails fast with a clear message if Tailscale is not installed on the node. Tailscale certs expire after ~90 days, and the daemon renews them itself: it re-reads its certificate every hour and, when less than a third of the lifetime is left (about 30 days for a 90-day cert), re-runs clusto cert (at most once every 12 hours). The renewed certificate is loaded into the running wss:// listener within the hour with no restart. This covers certificates issued by clusto cert (a *.ts.net name with the cert and key under <config dir>/tls/). A certificate you installed at another path is not renewed - the daemon logs a warning when it is due, so renew it yourself (a changed file is still hot-reloaded). Running clusto cert manually also needs no restart once TLS is already on; only the first-time enable needs clusto cert --restart. Any node with its own public-domain certificate works too; this just automates the Tailscale path.

Once a node serves TLS, connect to it by its Tailscale MagicDNS hostname (<node>.<tailnet>.ts.net), not a bare IP - the certificate is issued for that hostname, so an IP fails validation. The app auto-negotiates wss:// vs ws:// per connection profile, so there is no manual TLS toggle to set.

clusto project - Manage projects ​

clusto project <SUBCOMMAND>

Projects are working directories tracked by the cluster. They are the anchor point for file operations, git operations, and task scheduling.

clusto project ls ​

Lists all projects.

$ clusto project ls
ID                                     NAME                           DIR
a1b2c3d4-...                           my-app                         /home/user/my-app

clusto project new ​

clusto project new --name <NAME> --dir <DIR> [--description <DESC>] [--node <NODE_ID>]

Creates a new project. The working directory is resolved to an absolute path. Inside an agent session it follows the limits in Projects Created by Agents.

$ clusto project new --name "my-app" --dir /home/user/my-app
Project created: a1b2c3d4-...
  Name: my-app
  Dir:  /home/user/my-app

clusto project get <PROJECT_ID> ​

Shows full details for a project.

clusto project update <PROJECT_ID> ​

clusto project update <PROJECT_ID> [--name <N>] [--dir <D>] [--description <D>] [--node <N>] [--link <REPO>]

Updates a project. Only the fields you provide are changed. --link sets the project's repository link (github:owner/name or azure-devops:org/project/repo); an empty value (--link "") clears it. An explicit link overrides matching on the git remote.

clusto project clone ​

clusto project clone <URL> --path <DIR> [--node <NODE_ID>] [--as <USER>] [--name <NAME>] [--link <REPO>]

Clones a git repository onto a node and adds it as a project. <URL> is an HTTPS URL, an SSH URL or git@host:owner/name. --path is the new folder to clone into on the target node. --node defaults to the connected node, --as is the OS user to clone as (default: the node's session user), --name defaults to the repository name, and --link records the repository link (github:owner/name). The clone uses that user's own git credentials (gh auth, an SSH key or Git Credential Manager); no Clusto token is involved.

clusto project rm <PROJECT_ID> ​

Deletes a project. Sessions and files under the project directory are not affected.

clusto project import ​

clusto project import [--node <NODE_ID>]
clusto project import --all [--node <NODE_ID>]
clusto project import <PATH>... [--node <NODE_ID>]

Lists the folders Claude Code and Codex know on the node (default: the connected node), marked new, project or missing. With --all it imports every new folder; with paths it imports those. Folders that are missing or already a project are skipped. See Importing Projects.


clusto task - Manage scheduled tasks ​

clusto task <SUBCOMMAND>

Tasks are shell commands scheduled to run by the daemon.

Schedule formats ​

FormatExampleMeaning
onceonceRun once immediately
cron:<expr>cron:0_0_*_*_*_*Six-field cron expression with seconds first, in UTC (use _ instead of spaces). A 5-field expression is rejected; see Tasks
interval:<secs>interval:300Repeat every N seconds (N must be greater than 0)

clusto task ls ​

clusto task ls [--node <NODE_ID>]

Lists tasks with their status, schedule, owning node, project, command, and a RUN AS column with the account each task runs as and where it comes from (task, project, node_default or daemon). Use --node to show only tasks owned by one cluster node.

clusto task new ​

clusto task new --cmd <CMD> [--dir <DIR>] [--schedule <SCHED>] [--name <NAME>] [--project <ID>] [--node <NODE_ID>] [--user <NAME>]

Creates a new task. --node routes creation to that online cluster node. When it is omitted, the task is created on the connected node. --user runs the task as that OS account, which must exist on the task's node; without it the account comes from the project or the node (see Run as).

$ clusto task new --name "nightly-backup" --cmd "rsync -a /data /backup" --schedule "cron:0_0_2_*_*_*"
Task created: b2c3d4e5-...
  Name: nightly-backup

clusto task get <TASK_ID> [--node <NODE_ID>] ​

Shows full details for a task, including a Runs as: line with the resolved account and its source.

clusto task update <TASK_ID> [--node <NODE_ID>] ​

Updates a task on its owning node. Only provided fields are changed. --node selects the existing task's owner; it does not move the task to that node. --user <NAME> changes the account the task runs as, and --user "" clears the task's own account so the project or node default applies again.

clusto task move <TASK_ID> ​

clusto task move <TASK_ID> \
  --from-node <NODE_ID> \
  --to-node <NODE_ID> \
  --working-dir <ABSOLUTE_PATH> \
  [--project <PROJECT_ID>] \
  [--operation-id <OPERATION_ID>]

Moves a non-running task and its retained run history to another online node. The destination working directory is required and must exist on that node. An optional project must also exist on and belong to the destination node. Clusto preserves the task ID, schedule, configuration, and timestamps.

The CLI prints a generated operation ID before starting. If a recoverable phase fails, rerun the printed command with the same --operation-id; Clusto resumes the durable move instead of duplicating the task.

clusto task move-abort ​

clusto task move-abort \
  --operation-id <OPERATION_ID> \
  --from-node <NODE_ID> \
  --to-node <NODE_ID>

Aborts and cleans up a recoverable move that has not committed source removal. Use the same operation and node IDs printed by clusto task move.

clusto task rm <TASK_ID> [--node <NODE_ID>] ​

Deletes a task.

clusto task cancel <TASK_ID> [--node <NODE_ID>] ​

Cancels a running or pending task.

clusto task trigger <TASK_ID> [--node <NODE_ID>] ​

Triggers a task immediately, regardless of its schedule. A paused task can still be triggered.

clusto task pause ​

clusto task pause <TASK_ID> [--for <DURATION>] [--until <RFC3339 time>] [--node <NODE_ID>]

Pauses a task so it does not fire on its schedule. Retries do not fire either, and fires missed during the pause are skipped, not caught up. A run already in progress finishes normally, and clusto task trigger still works.

FlagMeaning
--for <DURATION>Pause for a length of time: a positive number with s, m, h, d or w (30m, 2h, 7d, 1w)
--until <RFC3339 time>Pause until this time, e.g. 2026-12-24T08:00:00Z

--for and --until are mutually exclusive. With neither, the task stays paused until you resume it. A timed pause ends on its own at the chosen time.

$ clusto task pause b2c3d4e5-... --for 2h

clusto task resume ​

clusto task resume <TASK_ID> [--node <NODE_ID>]

Ends a pause early. Paused tasks show paused in the STATUS column of clusto task ls, and clusto task get prints a Paused: line. See Tasks.


clusto report - Post results to the Reports feed ​

clusto report <SUBCOMMAND>

Posts markdown results, charts, and files to the Reports feed. Inside a scheduled task run the daemon sets CLUSTO_TASK_ID, CLUSTO_TASK_RUN_ID, and the local connection details, so no connection flags are needed and the report is linked to the run automatically.

clusto report post ​

clusto report post --title <TITLE> [--body <TEXT> | --body-file <PATH|->] [--level info|success|warning|error] [--attach <PATH>]... [--tag <TAG>]... [--task <UUID>] [--run <UUID>] [--project <UUID>] [--agent-session <ID>] [--json]

Posts a new report. --body-file - reads the markdown body from stdin. --level defaults to info. Repeat --attach for several files and --tag for several tags (at most 10). --task and --run override the ids taken from the task environment. --project overrides CLUSTO_PROJECT_ID; without either, a report posted from a terminal session takes that session's project. --agent-session records the Claude Code conversation that posted the report so it can be continued from the report; it defaults to CLAUDE_CODE_SESSION_ID in the environment, with the project folder from CLAUDE_PROJECT_DIR. --json prints the stored report.

$ clusto report post --title "App usage 2026-09-30" --body-file summary.md --level success --attach usage.png
report 7f3c9a10-... (1 attachment)

clusto report update <REPORT_ID> ​

clusto report update <REPORT_ID> [--title <TITLE>] [--body <TEXT> | --body-file <PATH|->] [--level <LEVEL>] [--tag <TAG>]...

Replaces the title, body, level, or tags of an earlier report.

clusto report ls ​

clusto report ls [--query <TEXT>] [--level <LEVEL>]... [--task <UUID>] [--project <UUID>] [--tag <TAG>] [--unread] [--archived] [--limit <N>] [--json]

Lists reports newest first across the cluster. --query searches the title, body, task name, and tags. --archived lists archived reports instead of the live feed. --limit defaults to 20 (max 200).

$ clusto report ls --tag nightly --limit 2
7f3c9a10-...  success  2026-09-30 08:00Z  * App usage 2026-09-30  (Daily stats)  [nightly]
51d0e2b4-...  warning  2026-09-29 08:00Z  App usage 2026-09-29  (Daily stats)  [nightly]

clusto report attach <REPORT_ID> <FILES>... ​

Attaches one or more files to an earlier report (10 MB each, 20 per report).

clusto report mcp ​

Serves report_post, report_update, report_attach, and report_list as MCP tools over stdio, for an agent's MCP config:

claude -p "..." --mcp-config '{"mcpServers":{"clusto-report":{"command":"clusto","args":["report","mcp"]}}}'

clusto agents - Agent instructions, skills, and commands ​

clusto agents <SUBCOMMAND>

Inspects and rolls out the Agent Docs configuration: the saved instructions, skills, subagents, and commands, rendered for a node and OS account. Inside a Clusto session the connection comes from the session environment, so an agent can check or apply its own configuration on the node it runs on.

Shared target options:

OptionMeaning
--project <UUID>Project scope for that project (default: user scope)
--node <UUID>Render for this node (default: the node the command connects to)
--user <NAME>OS account for user scope (default: the node's session account)

clusto agents tools [--json] ​

Lists the supported tools with their user and project instruction files and the kinds of items (skill, agent, command) each can hold.

clusto agents users [--node <UUID>] [--json] ​

Lists the OS accounts a node can write configuration for, marking the default. A root daemon lists the session account and every project run-as user; an unprivileged daemon only itself.

clusto agents status [--project <UUID>] [--node <UUID>] [--user <NAME>] [--json] ​

Compares the saved version, rendered for the node and account, with disk. Each enabled instruction file and tracked item prints its state (in-sync, missing, outdated, edited, diverged, n/a, no-tool, unsupported, error) and path.

$ clusto agents status
ovh-box / linux / ubuntu (/home/ubuntu)
in-sync      Claude Code                  /home/ubuntu/.claude/CLAUDE.md
outdated     Codex                        /home/ubuntu/.codex/AGENTS.md
no-tool      Gemini CLI                   /home/ubuntu/.gemini/GEMINI.md  (Gemini CLI is not set up for this user)
missing      skill deploy (claude)        /home/ubuntu/.claude/skills/deploy

clusto agents render [--project <UUID>] [--node <UUID>] [--user <NAME>] [--tool <KEY>] ​

Prints each enabled instruction file exactly as it would be written on that node, or the render error. --tool limits the output to one tool (claude, codex, gemini, ...), enabled or not.

clusto agents apply [--project <UUID>] [--node <UUID>] [--user <NAME>] [--only <KEYS>] [--docs-only] [--overwrite] [--json] ​

Writes the saved instructions and every tracked skill, subagent, and command of the scope. --only claude,codex limits the instruction files to those tools. --docs-only skips skills, subagents, and commands. Files edited on the node or never written by Clusto are skipped and listed; --overwrite replaces them.

clusto agents prune [--project <UUID>] [--node <UUID>] [--user <NAME>] [--apply] ​

Lists files Clusto wrote, nobody edited since, and nothing renders any more. Without --apply it is a dry run; with --apply it deletes them.

clusto agents vars [set|unset] ​

clusto agents vars
clusto agents vars set <NAME> <VALUE> [--node <UUID>]
clusto agents vars unset <NAME> [--node <UUID>]

Shows or changes the custom template variables used as {{clusto:name}}. Without --node the change applies to the cluster-wide default; with --node it sets or removes that node's override.

$ clusto agents vars set repos /data/Repos
repos = /data/Repos
$ clusto agents vars set repos 'C:\Repos' --node 3f2a...
repos = /data/Repos
repos = C:\Repos  [node 3f2a...]

clusto file - Manage project files ​

clusto file <SUBCOMMAND> <PROJECT_ID> ...

All file operations work on paths relative to a project's working directory. Path traversal outside the project root is rejected by the daemon.

clusto file ls <PROJECT_ID> [PATH] ​

Lists files in a project directory. PATH defaults to the project root.

$ clusto file ls a1b2c3d4-... src
dir              src/components/
file        1024  src/main.rs
file        2048  src/lib.rs

clusto file read <PROJECT_ID> <PATH> ​

Prints a file's contents to stdout.

$ clusto file read a1b2c3d4-... src/main.rs
fn main() { ... }

clusto file write <PROJECT_ID> <PATH> ​

Reads from stdin and writes to the file (overwrites). Use shell redirection:

bash
echo "hello" | clusto file write a1b2c3d4-... src/main.rs
cat local.rs   | clusto file write a1b2c3d4-... src/main.rs

clusto file touch <PROJECT_ID> <PATH> ​

Creates an empty file. Fails if the path already exists.

clusto file mkdir <PROJECT_ID> <PATH> ​

Creates a directory. The parent must already exist.

clusto file mv <PROJECT_ID> <FROM> <TO> ​

Moves or renames a file or directory. The destination must not already exist.

clusto file cp <PROJECT_ID> <FROM> <TO> ​

Copies a file or directory recursively. The destination must not already exist.

clusto file rm <PROJECT_ID> <PATH> ​

Deletes a file or directory. Directories are removed recursively.


clusto git - Git operations on a project ​

clusto git <SUBCOMMAND> <PROJECT_ID> ...

All git operations run against a project's working directory on the daemon host.

diff, stage and unstage take paths relative to the repository root, exactly as clusto git status prints them. For a project in a subdirectory of its repository, paths include that subdirectory, for example sub/src/main.rs. . or an empty path means the project directory.

clusto git status <PROJECT_ID> ​

Shows branch, ahead/behind count, staged changes, unstaged changes, and untracked files.

$ clusto git status a1b2c3d4-...
On branch main (upstream: origin/main, +1 -0)

Staged changes:
  M src/main.rs

Untracked files:
  ? scratch.txt

clusto git diff <PROJECT_ID> <PATH> [--cached] ​

Prints the unified diff for a file. Pass . for the whole project directory. --cached shows the staged diff (index vs HEAD); without it shows the unstaged diff (worktree vs index).

clusto git stage <PROJECT_ID> <PATH...> ​

Stages one or more files. Pass . to stage the whole project directory.

clusto git unstage <PROJECT_ID> <PATH...> ​

Unstages one or more files. Pass . to unstage the whole project directory.

clusto git commit <PROJECT_ID> --message <MSG> ​

Commits staged changes.

$ clusto git commit a1b2c3d4-... --message "fix: null pointer in parser"

clusto git pull <PROJECT_ID> ​

Pulls from the configured upstream.

clusto git push <PROJECT_ID> ​

Pushes to the configured upstream.


Cluster Usage ​

When using --nodes, the client connects to the first reachable node:

bash
# Connect to whichever node answers first - any node can serve the request
clusto --nodes 10.0.0.1:9178,10.0.0.2:9178 ls

# Environment variable form
export CLUSTO_NODES="10.0.0.1:9178,10.0.0.2:9178"
clusto ls

Leaderless clustering has no leader to find: every node serves reads and writes locally and gossips changes to its peers, so any reachable node returns the same cluster-wide view. The connected address is printed to stderr:

Connected to 10.0.0.1:9178 - clustod v1.14.41 (linux-x64)

Exit Codes ​

CodeMeaning
0Success
1Error (auth failure, connection refused, session not found, etc.)

Logging ​

Logs go to stderr, so they never mix with command output on stdout. Set the RUST_LOG environment variable to control them:

bash
RUST_LOG=debug clusto ls       # Verbose logging
RUST_LOG=warn clusto ls        # Only warnings (the default level is info)

Clusto - remote AI coding agents over WebSocket.