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
--nodes <NODES>	CLUSTO_NODES	(none)	Comma-separated cluster node addresses
--tls	CLUSTO_TLS	false	Connect over TLS (wss://)

*The token is optional in most cases. Local-only commands (ps, install, update, guide, daemon) never connect to a daemon. For commands that do connect, when --token/CLUSTO_TOKEN is not supplied the CLI falls back to the token stored in the local clustod config - so commands against the local node work out of the box. Supply --token explicitly only when targeting a remote node whose token differs from the local one.

When --nodes is set, the client tries each address until one succeeds. 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 SDK-mode session. The working directory is resolved to an absolute path. Prints the session ID on success.

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

clusto ls - List sessions

clusto ls

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

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

Status values: running, idle, detached, exited

clusto send - Send a prompt

clusto send <SESSION> <PROMPT>

Argument	Description
SESSION	Session ID (UUID)
PROMPT	The prompt text to send

Sends a prompt to an SDK-mode session. Spawns a new Claude process for the prompt. Automatically attaches to the session and streams output until completion.

$ clusto send 550e8400-e29b-41d4-a716-446655440000 "explain the main function"
{"type":"assistant","content":"The main function..."}

Output is Claude's raw stream-json format (one JSON object per line).

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 or you press Ctrl+C.

$ 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. The Role, Term, Leader ID, and Leader Address fields are vestigial under leaderless clustering - every node reports Role: Leader, Term: 0, and itself as the leader. Treat every node as a co-equal authority.

$ clusto cluster-status
Cluster Status
==============
  Node ID:        a1b2c3d4-e5f6-7890-abcd-ef1234567890 (node-a)
  Role:           Leader
  Term:           0
  Leader ID:      a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Leader Address: 10.0.0.1:9178

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

Returns an error if the connected node is not part of a cluster.

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 created: 7f3a2b10-...
  Mode: Adopted
  PID:  12345

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 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 terminal behaves like an attached session: you can send input (keystrokes) and receive output in real-time. To detach and later reattach, use clusto attach <session-id> in another terminal.

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 or codex agent, one provider and model per member (see teams.md). Create a team with clusto team create --name <n> --working-dir <dir> [--permission-mode bypass|accept_edits|plan] and add workers with clusto team spawn-worker <TEAM_ID> [--agent claude|codex] [--model <m>|--tier fast|balanced|deep] [--role <r>]. 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 hive-team MCP tools; the subcommands below are the CLI mirror of those tools.

clusto team ls

Lists all active teams.

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

clusto team get <TEAM_ID>

Shows details for a specific team.

$ clusto team get a1b2c3d4-e5f6-7890-abcd-ef1234567890
Team:    a1b2c3d4-...
Name:    my-team
Status:  Running
Leader:  550e8400-...
Workers: 3
  - 6ba7b810-...
  - 7c8d9e0f-...
  - 8d9e0f1a-...

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 hive-team MCP tools (see teams-autopilot.md); these subcommands mirror those tools for shell scripts, humans, and non-Claude (PTY) leaders:

Command	Purpose
clusto team handoff <TEAM_ID> --name <n> --prompt <p> [--agent claude|codex] [--model <m>|--tier fast|balanced|deep] [--role <r>]	Spawn worker + block until report. Returns a wait_id on timeout.
clusto team assign <TEAM_ID> --name <n> --prompt <p> [--agent ...] [--model <m>|--tier <t>] [--role <r>]	Spawn worker and return immediately. Pair with wait.
clusto team send <TEAM_ID> [--to <id> | --broadcast] --message <m>	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>	Print the roster with per-worker status (pending / reported(success|failure)).
clusto team report <TEAM_ID> --success|--failure [--result <s>]	Worker reports its result. Auto-called by the Claude Stop hook.
clusto team summary <TEAM_ID> [--result <s>]	Leader publishes a progress summary. Teams are persistent - this does not end the team.
clusto team models [--provider <p>] [--refresh] [--json]	List the models this node offers per agent CLI, with tier and the recommended pick.
clusto team wait <TEAM_ID> [--for <ids>] [--timeout <secs>] [--wait-id <id>]	Bounded block on pending workers.
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.

clusto team mcp runs the stdio MCP server that exposes these operations as mcp__hive-team__* tools. The daemon wires it into each headless agent via --mcp-config; it is not meant to be run by hand. New Claude 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 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     CMD
12345   claude --print --output-format stream-json ...
67890   claude --print --output-format stream-json ...

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.12.9
platform:      linux-x64
clustod (local): clustod 1.12.9

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)	User secret to set in daemon config
--json	false	Output a single JSON summary line (for automation)

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.

The wizard prompts for: display name, port, bind address, token, claude binary path, and optional cluster settings. The config is written to the platform config directory.

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 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.

Install paths:

• Windows: %LOCALAPPDATA%\Programs\Clusto\clustod.exe
• Linux/macOS: /usr/local/bin/clustod

$ sudo clusto install
Installing Clusto daemon...
  Binary:  /usr/local/bin/clustod
  Config:  /root/.config/clusto/Clusto/config.toml
  Client:  /home/alice/.config/clusto/config.toml
  Claude:  /home/alice/.local/bin/claude
  Token:   a3f8b2c1d4e5...
Daemon started (systemd unit clustod.service).

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

Renames a cluster node. The name is saved to the node's config file and propagated to all peers immediately.

$ 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>	local node's [update].channel, else semi-stable	Release channel: semi-stable or unstable
--remote-token <TOKEN>	$CLUSTO_UPDATE_TOKEN, else local node's [update].token	Bearer token for private remote manifests

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 and channel the node itself tracks. So on a node set to the unstable channel, a plain clusto update pulls the unstable CLI; no flags needed. --from, --channel, and --remote-token override the config values. The concrete manifest file is derived from the channel (manifest.json for semi-stable, manifest-unstable.json for unstable). The binary is verified by SHA-256 before the running CLI is replaced and restarted.

Examples:

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

# Force the unstable channel for this update only
clusto update --channel unstable

# 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/

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>	local node's [update].channel, else semi-stable	Release channel: semi-stable or unstable
--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

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 and channel 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, --channel, and --remote-token override the config values.

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.

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

# Force the unstable channel for this update only
clusto update-node --channel unstable

# 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

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

clusto discover - Discover Clusto nodes on Tailscale

clusto discover

Scans the Tailscale network for other Clusto nodes. Prints discovered nodes with their address, version, and platform. The scan identifies TLS-only nodes (those that serve wss:// and reject plain ws://) too. Does not require a daemon connection.

$ clusto discover
ADDRESS              VERSION   PLATFORM
100.64.1.2:9178      1.8.103   linux-arm64
100.64.1.3:9178      1.8.103   windows-x64

clusto daemon - Local daemon management

clusto daemon <SUBCOMMAND>

Read-only subcommands for inspecting the locally installed daemon. These read the local config file directly and do not require a daemon connection.

clusto daemon get-token

Prints the auth token from the local daemon config.

$ clusto daemon get-token
a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5...

clusto daemon get-config

Prints the full daemon config as TOML.

$ clusto daemon get-config
[daemon]
name = "my-node"
port = 9178
...

clusto daemon status

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

$ clusto daemon status
Installed: yes
Version:   1.8.103
Running:   yes (PID 4321)

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, so the web client only connects to nodes that serve TLS (wss://). 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 - re-run to renew, then restart the daemon. 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.

$ 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>]

Updates a project. Only the fields you provide are changed.

clusto project rm <PROJECT_ID>

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

---

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_*_*_*_*	Cron expression (use _ instead of spaces)
interval:<secs>	interval:300	Repeat every N seconds

clusto task ls

clusto task ls [--node <NODE_ID>]

Lists tasks with their status, schedule, owning node, project, and command. 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>]

Creates a new task. --node routes creation to that online cluster node. When it is omitted, the task is created on the connected node.

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

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

Shows full details for a task.

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.

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.

---

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:

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.

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. --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 everything.

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

Unstages one or more files. Pass . to unstage everything.

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:

# 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

Exit Codes

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

Logging

Set the RUST_LOG environment variable to control log output:

RUST_LOG=debug clusto ls       # Verbose logging
RUST_LOG=warn clusto ls        # Only warnings (default)