---
url: https://clusto.app/docs/cli.md
description: >-
  Reference for the clusto command-line client, including sessions, teams,
  tasks, files, updates, and daemon administration.
---

# 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`](#clusto-profile-saved-connection-profiles)) |

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](#clusto-profile-saved-connection-profiles).

\*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](/node-identity).

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: 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/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](/session-exclusivity), 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`](#clusto-team-manage-agent-teams)), 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-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]
```

| 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](/clustering#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]
```

| 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-work
```

### `clusto 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](/configuration#commands) 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](/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](/teams#team-tab-beside-the-conversation)
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](/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](/agent-attention).
`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](/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](https://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](/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](/knowledge#mcp-tools). 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](/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](/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](/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](/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`](/remote-updates#terminals-that-survive-a-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](/troubleshooting#_18-node-identity-changed-or-an-identity-changed-badge)).
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](/remote-updates#terminals-that-survive-a-restart) 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](/session-credentials), `--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](/migrating-from-hive#repair-or-finish-a-stuck-node).

### `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](/knowledge#lessons).

### `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`](#clusto-mcp-knowledge-mcp-server) 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`](#clusto-lessons-review-agent-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](/knowledge#tools-from-a-shell) and
[Time tracking](/time-tracking#ask-an-agent).

### `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]
```

| 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](/downloads#set-up-this-computer-from-the-app) |
| `--user` | `false` | Install for the current account only, without root or Windows administrator rights. See [Install without sudo](/downloads#install-without-sudo-or-administrator-rights). 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`](#clusto-doctor-check-this-node-s-daemon-install-cluster-and-ai-setup)
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.

| | 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-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](/remote-updates#terminals-that-survive-a-restart)
  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>
```

| 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](/remote-updates#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](/remote-updates#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](/remote-updates#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](/session-credentials), 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`

```
clusto daemon link [--node <UUID>] [--cloud <URL>]
```

Links a node to your Clusto account so the [web relay](/clusto-tunnel#linking-a-node-to-your-account)
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](#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](/node-identity#pairing-codes). 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](/node-identity#when-an-identity-changes) 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](/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-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](/configuration#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](/project-import).

***

### `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](/tasks#defining-a-task) |
| `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](/tasks#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.

| 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 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](/tasks#pausing-a-task).

***

### `clusto report` - Post results to the Reports feed

```
clusto report <SUBCOMMAND>
```

Posts markdown results, charts, and files to the [Reports](/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](/reports#continue-the-run-s-session); 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](/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/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

| 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)
```
