Appearance
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>| Option | Env Var | Default | Description |
|---|---|---|---|
--host <HOST> | CLUSTO_HOST | 127.0.0.1 | Daemon host address |
--port <PORT> | CLUSTO_PORT | 9178 | Daemon 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 |
--tls | CLUSTO_TLS | false | Use 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_PROFILE | the default profile | Saved 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]| Option | Short | Default | Description |
|---|---|---|---|
--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: refactorclusto ls - List sessions
clusto lsLists 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/otherMode 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/Option | Description |
|---|---|
SESSION | Session ID (UUID) |
PROMPT | The prompt text to send |
--detach | Return 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...]| Argument | Description |
|---|---|
SESSION | Session ID (UUID) |
TAG | One 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/Option | Description |
|---|---|
SESSION | Session ID (UUID) |
--format | Output 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-statusDisplays 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 yesA 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]| Option | Default | Description |
|---|---|---|
--node <ID> | the connected node | The node to read or change (UUID) |
--set <ID,ID,...> | (none) | Allow only these nodes (comma-separated UUIDs). The node itself always may |
--any | off | Let 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-f12345678901While 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]| Option | Short | Default | Description |
|---|---|---|---|
--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-workclusto open - Open a terminal on the daemon
clusto open [OPTIONS]| Option | Short | Default | Description |
|---|---|---|---|
--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-teamclusto 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:
| Command | Purpose |
|---|---|
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 status | Print 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 lsclusto 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.
| Topic | Covers |
|---|---|
setup | Connection order (flags, env vars, profile), tokens, TLS, clusters |
sessions | Delegating to a session without streaming its transcript |
teams | Headless and led teams, workers, wait, merge |
tasks | Creating scheduled tasks, cron syntax, injected run variables |
reports | clusto report and the report MCP tools |
projects | clusto project, clusto file, clusto git |
mcp | Installing 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.
| Subcommand | Does |
|---|---|
list | Lists 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 mcpServes 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.
| Subcommand | What it does |
|---|---|
ls | List installed plugins |
inspect | Show what a git URL or folder on the connected node would add, without installing it. --ref picks a branch, tag or commit |
install | Install 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 |
update | Move a git plugin to a new commit, or re-read a folder plugin's manifest. --ref picks the branch, tag or commit |
rm | Uninstall from every node |
enable, disable | Turn a plugin on or off without uninstalling it |
status | Install state of every plugin on a node (default: the connected node) |
logs | Tail of a plugin's log on a node |
view | Render a plugin view and print the reply as JSON. --param key=value can be repeated |
run | Run 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:
| Diagnosis | Meaning |
|---|---|
| Not installed | No daemon found. Run clusto install |
clustod running | Healthy. An old hived service may stay registered but disabled during the rollback window; that is normal |
clustod stopped | The service is installed but not running |
| Both running (conflict) | hived and clustod are active at the same time |
| Cutover in progress | The journaled Hive to Clusto cutover has started and not finished. Check again in a minute |
| Cutover stopped part-way | The 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 back | The cutover failed and was undone. Shows the target version and the recorded error. Each newer daemon version retries once |
Stale hived registration | A hived service is registered but its program is gone |
| Hive-era node stopped / running | An old hived node that has not moved to clustod yet |
| Hive data with no daemon | Hive 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:
| Mark | Finding | Repair with --fix |
|---|---|---|
FAIL | A 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 |
WARN | A 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 |
WARN | A 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) |
WARN | A connected peer runs another Clusto version. Mixed versions are not supported and can break terminals and chats | Update 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
hivedthat sits next toclustod; - 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 replacehivedwithclustod. 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
clustobundles in place ofhived, 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 (
hivedruns again, or the journal has not moved for 10 minutes), rolls it back with the bundled daemon, which returns the node tohived, then installs the bundled daemon and lets the cutover run again; - removes a stale
hivedservice registration, and a stoppedclustodregistration 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>]| Subcommand | Does |
|---|---|
pending | Lessons 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 |
list | Approved lessons for a repository (default: the current directory) |
propose | Proposes 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.
| Command | Does |
|---|---|
notes vaults, ls, search, read | List the vaults, list a vault, search it, and print one note with its SHA-256 |
notes write | Creates 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 rm | Move or rename a note or folder (never overwrites), and delete a note or an empty folder |
time status, start, stop, ls | The running timer and today's entries, start and stop the timer, and list entries (default: the last 7 days) |
time add, edit, rm | Book a finished entry with explicit times, change one (omitted options keep their value, --project "" removes the project), delete one |
time project add, edit, rm | Create, rename, recolor, archive or delete a time project. Its entries stay, without a project, when it is deleted |
tool ls | Lists 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 psLists 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 claudeclusto version - Show version information
clusto versionPrints 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.41clusto install - Install the daemon
clusto install [OPTIONS]| Option | Default | Description |
|---|---|---|
--non-interactive | false | Skip interactive prompts, use defaults |
--name <NAME> | (none) | Node display name (skips name prompt) |
--port <PORT> | 9178 | Daemon listen port (skips port prompt) |
--bind <ADDR> | 0.0.0.0 | Bind 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-code | false | Create 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 |
--user | false | Install for the current account only, without root or Windows administrator rights. See Install without sudo. Do not run it under sudo |
--reinstall | false | Replace the config of a machine that already has clustod. Needed for non-interactive runs; the wizard otherwise asks first |
--json | false | Print 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
hivedservice or Hive state) it prints the doctor diagnosis and offers the in-place upgrade:Repair the existing node now? [Y/n]. Answering yes does whatclusto doctor --fixdoes and keeps the data, token and sessions.--non-interactiverepairs without asking. With--jsonit never repairs and fails with the diagnosis. - On a machine that already has
clustod, it asksReinstall 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 | iexThe 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.
| Linux | macOS | Windows | |
|---|---|---|---|
| Install dir | ~/.local/bin | ~/.local/bin | %LOCALAPPDATA%\Programs\Clusto |
| Config | ~/.config/clusto/config.toml | per-user config | per-user config |
| Autostart | systemd user unit ~/.config/systemd/user/clustod.service (Restart=always), enabled, plus loginctl enable-linger | LaunchAgent ~/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-runashelper 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 --userrefuses when a systemclustodexists, and a plainclusto installrefuses when a user install exists (remove it first withsystemctl --user disable --now clustod). - Self-update, restart and surviving terminals work under the user manager. The system-only
/etcdrop-ins (priority hardening, holder slice,tailscaledweight) are skipped. - On Linux,
clusto doctorshows 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.tomlclusto rename-node - Rename a cluster node
clusto rename-node <NODE_ID> <NAME>| Argument | Description |
|---|---|
NODE_ID | Node UUID (from clusto cluster-status) |
NAME | New 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]| Option | Default | Description |
|---|---|---|
--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].token | Bearer token for private remote manifests |
--version <X.Y.Z> | newest release | Install this exact release from its per-version manifest; only the 10 most recent releases stay published |
--dry-run | false | Verify 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]| Option | Default | Description |
|---|---|---|
--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].token | Bearer token for private remote manifests |
--refresh-artifacts | false | Also refresh remaining artifacts for other platforms and app clients |
--version <X.Y.Z> | newest release | Install this exact release from its per-version manifest; only the 10 most recent releases stay published |
--cluster | false | Update 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-run | false | Verify 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.29Nodes 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-daemonstill works as an alias.
clusto discover - Discover Clusto nodes on Tailscale
clusto discoverAsks 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 workstationclusto 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: yesclusto daemon link
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.
| Option | Description |
|---|---|
--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.
| Subcommand | Does |
|---|---|
add | Adds 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 |
show | Prints a profile (default: the default profile) with the token masked |
use | Makes 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 overrideclusto 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 clearManages 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.
| Subcommand | Does |
|---|---|
generate | Creates 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 |
set | Sets 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 |
status | Shows 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 |
clear | Removes 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>| Subcommand | Does |
|---|---|
show | Prints 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 |
forget | Drops 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.
| Option | Description |
|---|---|
--name <NAME> | Domain to issue the cert for. Defaults to this machine's Tailscale MagicDNS name. |
--restart | Restart 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-appclusto 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-appclusto 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
| Format | Example | Meaning |
|---|---|---|
once | once | Run 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:300 | Repeat 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-backupclusto 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.
| Flag | Meaning |
|---|---|
--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 2hclusto 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:
| Option | Meaning |
|---|---|
--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/deployclusto 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.rsclusto 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.rsclusto 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.txtclusto 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 lsLeaderless 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
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Error (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)