# 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](./overview.md) 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

```bash
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:

```bash
# 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](../commands/adding-removing.md), an [interactive terminal](../terminal/basics.md), or an [agent](../agents/what-are-agents.md).

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

```bash
# 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](../agents/what-are-agents.md). This requires `--agent-tool-id`; run `solo agents list` to see the configured [agent tools](../agents/setting-up-tools.md) and their IDs. Pass extra command-line arguments to the agent with `--arg`, repeated once per argument.

```bash
# 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.

```bash
# 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:

```bash
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](../commands/trust-security.md); `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](./todos-and-scratchpads.md)
- [JSON output and scripting](./json-output-and-scripting.md)
- [HTTP API](../integrations/http-api.md) — the underlying API these commands call

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/cli/projects-and-processes