Projects and processes from the CLI

The solo projects, solo processes, and solo commands groups let you manage projects and control their processes without touching the app window. All of them require the Solo app to be running — see the CLI overview for setup.

Every command accepts --json for machine-readable output; the examples below mostly show human output. IDs are the numeric IDs Solo assigns to projects and processes — use the list commands to find them.

Projects#

solo projects list [--offset <n>] [--limit <n>] [--json]
solo projects get <id> [--json]
solo projects create <name> <existing-path> [--json]
solo projects rename <id> (<display-name> | --clear) [--json]
solo projects delete <id> [--confirm-stop-running] [--json]

• list shows every project with its ID, name, and path. Use --offset and --limit to page through long lists.
• create registers an existing local directory as a Solo project. The path must already exist.
• rename sets a display name shown in the app; the underlying project name and path are unchanged. Pass --clear instead of a name to remove the display name.
• delete removes the project from Solo along with its processes, todos, scratchpads, and other project-scoped data; your files on disk are not touched. If any of the project's processes are running, the command refuses unless you pass --confirm-stop-running, which stops them first.

Examples:

# Register a project and list what exists
solo projects create my-app ~/Code/my-app
solo projects list
 
# Give project 3 a friendlier display name, then clear it
solo projects rename 3 "My App (staging)"
solo projects rename 3 --clear
 
# Delete project 3 even if processes are running
solo projects delete 3 --confirm-stop-running

Processes#

A process is one tab in a project: a configured command, an interactive terminal, or an agent.

solo processes list [--project-id <id>] [--status <status>] [--offset <n>] [--limit <n>] [--json]
solo processes get <id> [--json]
solo processes spawn --project-id <id> --kind terminal [--name <name>] [--json]
solo processes spawn --project-id <id> --kind agent --agent-tool-id <id> [--name <name>] [--arg <arg> ...] [--json]
solo processes start <id> [--json]
solo processes stop <id> [--json]
solo processes restart <id> [--json]
solo processes rename <id> <new-name> [--json]
solo processes delete <id> [--project-id <id>] [--confirm-stop-running] [--json]
solo processes output <id> [--project-id <id>] [--lines <n>] [--raw] [--json]

Listing and inspecting#

list shows all processes across every project by default. Narrow it with --project-id, or filter by state with --status, which accepts stopped, starting, running, stopping, exited, or failed.

# Everything currently running, in any project
solo processes list --status running
 
# All processes in project 2
solo processes list --project-id 2

get shows one process, including its kind, command, status, PID, and uptime.

Spawning terminals and agents#

spawn creates a new process and starts it immediately. Two kinds are supported:

• --kind terminal opens a new interactive terminal in the project.
• --kind agent starts an AI coding agent. This requires --agent-tool-id; run solo agents list to see the configured agent tools and their IDs. Pass extra command-line arguments to the agent with --arg, repeated once per argument.

# Find agent tool IDs
solo agents list
 
# Open a terminal in project 2
solo processes spawn --project-id 2 --kind terminal --name scratch
 
# Start an agent with an initial task
solo processes spawn --project-id 2 --kind agent --agent-tool-id 1 \
  --name reviewer --arg "review the open pull request"

Lifecycle and output#

start, stop, and restart operate on one process by ID. rename changes its display name. delete removes the process entirely; if it's running, pass --confirm-stop-running to stop it first.

output prints recent output from a process — the last 50 lines by default, adjustable with --lines. By default you get rendered terminal rows (what you'd see on screen); pass --raw for the raw output stream instead.

# Tail the last 200 rendered lines from process 9
solo processes output 9 --lines 200
 
# Raw output, useful for parsing logs
solo processes output 9 --raw --lines 500

Bulk commands#

The solo commands group operates on all of a project's configured command processes at once, mirroring the app's start-all and stop-all controls:

solo commands start-all --project-id <id> [--json]
solo commands stop-all --project-id <id> [--json]
solo commands restart-all --project-id <id> [--json]

start-all and restart-all only start commands the project trusts; stop-all stops every running command process. The output reports which commands were started, skipped, or failed.

Related pages#

• Todos and scratchpads from the CLI
• JSON output and scripting
• HTTP API — the underlying API these commands call