SyndicateDocs

Command reference#

syndicate is the local operator command. It reads ~/.config/syndicate/config.json and talks to the Host over the local control socket in ~/.local/state/syndicate/run. Every command runs as the Syndicate user; there is no remote invocation.

Commands#

Command Purpose
syndicate version [--json] Print the installed CLI version.
syndicate setup [--non-interactive] [flags] Write base configuration. See Configuration.
syndicate status [--json] Report the Host's current status without waiting.
syndicate doctor [--json] Run the local checks and read the Host's diagnostics.
syndicate dashboard [--no-open] Print a single-use dashboard invitation URL.
syndicate host run|start|stop|restart|status|logs Run the Host in the foreground, or drive the user service.
syndicate agent list [--json] Probe every supported agent CLI.
syndicate agent status <codex|claude|packetcode|all> [--json] Probe one agent, or all of them.
syndicate agent install <agent|all> [--require-all] [--json] Run the supported install path for an agent.
syndicate agent login <codex|claude> Hand over to the vendor CLI's own login command.
syndicate agent configure packetcode Hand over to PacketCode's own configuration command.
syndicate workspace list [--json] List Host workspaces.
syndicate session list [--json] List durable sessions.
syndicate session attach <id> [--take-control] Attach the terminal to a durable session.
syndicate session stop <id> Request that a durable session stop.
syndicate workstation [repository] [--name name] [--detach] Create or converge a workstation.
syndicate workstation list|attach|status|stop Manage existing workstations.

Running syndicate with no arguments is a compatibility alias for syndicate host run.

Waiting for the Host#

The workstation commands retry the connection while the Host starts, for about seventy seconds, and print each retry to standard error. Creating or converging a workstation also waits for the terminal runtime to report ready, so a cold boot that is still running migrations does not look like a failure.

Every other command connects once and reports what it finds. status and doctor deliberately never wait, which is what makes them safe to poll from a script.

Doctor#

syndicate doctor runs one check for configuration, one for the configuration lock, one for tmux, one for the Host, and one for each configured workstation. It exits 1 if any check fails and 0 otherwise; a warning does not fail the command.

syndicate doctor --json prints schemaVersion and the checks array, each entry carrying an id, a status and a one-line summary. The Host check fails and names the socket path when the local control socket is absent or does not answer.

Agent probes#

syndicate agent list prints one line per agent: the agent id, its state, the reported version, and either the resolved absolute executable path or the reason it could not be used.

  • --json returns the full probe for each agent, including the availability, sign-in, ownership and configuration fields that the one-line form omits.
  • Sign-in state comes from the CLI's own status output. An agent that answers with nothing recognisable is reported as unknown, never as signed in.
  • syndicate agent status exits 1 unless every agent it probed is available and not broken, so it can gate a script.

Syndicate never handles provider credentials. syndicate agent login runs the vendor CLI's own login command in your terminal; the credentials stay in that CLI's store.

Attaching a session#

syndicate session attach requires an interactive terminal. It returns to the shell when you detach or when the provider session ends. A command that is killed by a signal exits non-zero, so a wrapper script can tell an interrupted attach from a clean exit.