Reference

CLI Reference

roam is a single binary. Every subcommand acts on the daemon over a Unix socket at .roam/roam.sock. If the daemon is not running, commands that need it will tell you.

About this page

roam --help

The output of roam --help is the canonical command list. This page groups and annotates each command, but the binary is the source of truth.

Setup

roam init

Create a new session. Runs the onboarding wizard (topology, harnesses, template, runtime mode, adoption scan, approval gates, and notifications) and scaffolds the directory structure under ~/ROAM/<session-name>/ by default.

roam init <project-name>
roam init <project-name> --from-template <template-name>

The wizard pre-provisions agents if you pick a template. Four built-in templates: investor, software, research, marketing. The --from-template flag skips the wizard and clones a previously saved template (see roam template).

After init, start the daemon when you are ready to run the workspace.

roam config

View or edit session configuration. Without arguments, prints the current config.

roam config
roam config set goal "Ship the investor deck by Friday"
roam config set strategy quality_optimized
roam config set mode continuous
roam config set eydii mode alert-only

Valid strategies: balanced, latency_optimized, quality_optimized, cost_optimized. Valid modes: continuous, work_hours.

roam security

Run a security posture audit. Checks directory permissions, agent tokens, signing keys, file integrity signatures, credential protection, and injection scanning status.

roam security
roam security --fix

--fix repairs issues it finds: restores directory permissions to 0o700, regenerates missing signing keys, fixes credential file permissions.

roam upgrade

Manage your license tier. Tiers control the maximum number of harnesses you can use in a session.

roam upgrade

Runtime

roam daemon

Start, stop, or inspect the coordination daemon. The daemon is a background Node.js process that manages the Unix socket, runs heartbeat checks, drift sweeps, task routing, and the EYDII trust layer.

roam daemon start
roam daemon stop
roam daemon status
roam daemon pause
roam daemon resume

Subcommand	What it does
`start`	Spawns the daemon as a detached process. Loads optional local provider credentials into its environment when configured. Writes PID to `.roam/roam.pid`.
`stop`	Sends SIGTERM to the daemon process.
`status`	Pings the daemon over the socket. Reports PID and uptime.
`pause`	Suspends all periodic tasks (heartbeat checks, drift sweeps, digest updates). In-flight work finishes to a clean boundary. State is flushed to disk. Safe for migration: copy the directory while paused.
`resume`	Reactivates periodic tasks.

roam status

Show the current session status. If the daemon is running, fetches a live digest over the socket. Otherwise falls back to the cached digest on disk.

roam
roam status

Running roam with no arguments is the same as roam status. If no session exists, you get the setup welcome menu.

roam mode

View or change the routing strategy.

roam mode
roam mode quality_optimized

Without arguments, shows all four strategies with the active one marked.

roam dashboard

Terminal dashboard. Shows agents, tasks, drift scores, health, and recent events in a formatted table view.

roam dashboard
roam dash
roam dashboard --watch
roam dash -w

--watch (-w) enables live mode — the dashboard refreshes on each daemon digest update.

roam human

Set the operator's availability state. Agents that are waiting on human input respond to this signal.

roam human present
roam human away
roam human focused
roam human on_deck

Agents

roam agent

Manage agents in the session.

roam agent add <name> --framework <framework> --role <role>
roam agent remove <agent-id>
roam agent list
roam agent debug <agent-id>

Subcommand	What it does
`add`	Registers a new agent. Harness defaults to `claude-code` if omitted. Role defaults to the agent name if omitted. The daemon assigns an identity token and creates the agent's working directory.
`remove`	Archives the agent. Reassigns its in-flight tasks.
`list`	Table of all registered agents with ID, name, harness, role, and state. States are color-coded: ACTIVE (green), QUARANTINED (red), DRIFTING (yellow).
`debug`	Deep inspection of a single agent. Shows registration info, last heartbeat, recent peer reports, current state, four artifacts with sizes, and trust score.

Supported harnesses and runtimes:

claude-code   claude-cowork  openai      chatgpt
openclaw      cursor         google-adk  gemini
langchain     langgraph      crewai      n8n
agno          mastra         dify        ollama
lm-studio     open-webui     flowise     mcp

roam task

Manage tasks.

roam task add "<description>" --capability <cap> --priority <priority>
roam task add "<description>" --capability <cap> --depends-on task-id-1,task-id-2
roam task assign <task-id>
roam task list
roam task list --state in_progress
roam task cancel <task-id>
roam task redirect <task-id> <payload>
roam task deprioritize <task-id>
roam task done <task-id>

Subcommand	What it does
`add`	Creates a task. Priority is `low`, `normal` (default), `high`, or `critical`. Dependencies are comma-separated task IDs.
`assign`	Triggers the router to find the best agent and assign the task.
`list`	Table of all tasks. Filterable by state. States: `queued`, `claimed`, `in_progress`, `done`, `failed`, `blocked`, `abandoned`.
`cancel · redirect · deprioritize`	Writes an interrupt signal to `.roam/interrupts/`. The assigned agent picks it up on its next poll cycle (via `checkInterrupts()` in the SDK).

roam instructions

Generate system prompt instructions for an agent. The output is a Markdown file that you paste into your agent's system prompt to teach it the ROAM coordination protocol — how to file intents, read verdicts, write heartbeats, and update its four artifacts.

roam instructions
roam instructions <role-slug>

Without a role slug, generates instructions for all roles. Output goes to .roam/instructions/<role>.md.

roam handoff

Transfer responsibilities from one agent to another. Copies all four artifacts, reassigns in-flight tasks, and transitions both agents' states.

roam handoff <departing-agent-id> <incoming-agent-id>

Reports latency and warns if it exceeds the 90-second target.

roam report

File a drift report against an agent. Used by humans (or other tooling) to flag observed behavioral issues.

roam report <agent-id>

Audit

roam drift

Run drift detection on agents.

roam drift sweep
roam drift <agent-id>

sweep assesses all active agents. Shows composite drift score as a percentage with a bar chart. Agents above the critical threshold (70%) are auto-transitioned to DRIFTING. Passing an agent ID runs a deep assessment of one agent — score, critical report count, transition status, and recent peer reports with evidence.

roam log

Tail daemon or agent logs.

roam log
roam logs daemon 50
roam log <agent-id>
roam log <agent-id> 100

Default target is daemon. Default line count is 20. Daemon logs are JSON lines from .roam/daemon.log. Agent logs are from agent-logs/<agent-id>/.

roam export

Export session data for backup, migration, or analysis.

roam export json
roam export snapshot ./my-snapshot
roam export archive ./backup.tar.gz

Format	What's in it
`json`	Single JSON file with config, agents, tasks, state, heartbeats, drift scores, artifacts, peer reports, and digest.
`snapshot`	Directory copy of all session data (excluding secrets and runtime files).
`archive`	Tarball of the full session directory. Excludes agent logs, observer queue, PID, and socket.

roam import

Restore a session from an archive or snapshot.

roam import ./backup.tar.gz
roam import ./my-snapshot

Integrations

roam telegram / roam discord

Connect Telegram or Discord as ROAM command surfaces: 10 commands plus drift, quarantine, task, and health notifications.

roam telegram setup
roam telegram start
roam telegram status
roam discord setup
roam discord start
roam discord status

Subcommand	What it does
`setup`	Interactive prompt for the bot token and destination. Saves local command-surface config with owner-only permissions.
`start`	Starts the selected Telegram or Discord command surface.
`status`	Shows enabled/disabled state, masked destination IDs, and which command and notification surfaces are active.

roam adopt

Import an existing agent workspace into ROAM. Scans a directory for agent artifacts, runs a baseline quality exam, and migrates the agent into the session.

roam adopt scan <path>
roam adopt import <path> <role-name>
roam adopt list
roam adopt bulk <path>

Subcommand	What it does
`scan`	Detects agent ID, harness/runtime, artifact count, and last activity.
`import`	Creates a registered agent from the scanned workspace. Role is a positional argument.
`list`	Lists detected adoption candidates.
`bulk`	Imports multiple detected candidates from a workspace root.

roam template

Save, list, or delete session templates. Templates capture the session config, registry, doctrine, and agent working directories so you can clone setups.

roam template save <name>
roam template list
roam template delete <name>

roam gui

Open the browser-based Command Center.

roam gui
roam ui

Utility

roam about        # Splash screen and runtime info
roam --welcome    # Same as roam about
roam readme       # Print the README to the terminal
roam help         # Print command help
roam --help

Common workflows

Cold start

roam init my-project
# Answer the wizard
roam daemon start
roam task add "Research competitor landscape" --capability researcher --priority high
roam dashboard --watch

Recover from a quarantine

An agent gets quarantined when its heartbeat times out or its drift score crosses the critical threshold. To investigate and recover:

roam agent debug <agent-id>
roam drift <agent-id>
roam log <agent-id> 50
# Fix the issue (restart the harness, add budget, etc.)
roam agent add <new-name> --framework <fw> --role <role>
roam handoff <quarantined-id> <new-id>

Rotate provider credentials

roam daemon pause
# Edit local provider credentials if configured
roam daemon resume
roam status
roam security

Environment variables

Variable	Purpose
`ANTHROPIC_API_KEY`	Claude Code / Claude
`OPENAI_API_KEY`	OpenAI / ChatGPT / Cursor
`GOOGLE_API_KEY`	Gemini / Google ADK
`N8N_API_KEY`	n8n
`OLLAMA_HOST`	Ollama (self-hosted)
`LM_STUDIO_HOST`	LM Studio (self-hosted)
`ROAM_OPERATOR_NAME`	Your display name (defaults to `$USER`)
`NO_COLOR`	Disable ANSI colors
`ROAM_NO_SPLASH`	Skip banner on startup
`ROAM_QUIET`	Quiet mode