# Solo CLI overview

The `solo` command is a companion CLI for the Solo desktop app. It talks to the running app over its local [HTTP API](../integrations/http-api.md), so you can inspect and control projects, processes, todos, and scratchpads from any terminal or script.

## Requirements

- The Solo desktop app must be running for commands that inspect or control app state. Built-in help and `solo --version` do not contact the app.
- The **HTTP API** must be turned on in Solo's settings. The CLI connects through this API.

## Installing the CLI

The CLI binary ships inside the Solo app, so there is nothing extra to download.

1. Open **Settings** and choose the **MCP** tab. The default shortcut is `Cmd+,` on macOS and `Ctrl+,` on other platforms; it can be rebound or disabled in **Hotkeys** settings.
2. Turn on **HTTP API**.
3. If you use a POSIX shell, copy the install snippet shown under the HTTP API section and run it in a terminal.

The current snippet is for POSIX shells. It creates `~/.local/bin` if needed, symlinks the bundled CLI binary to `~/.local/bin/solo`, and runs the installed command's `--version` check:

```bash
mkdir -p "$HOME/.local/bin"
ln -sf /path/to/bundled/solo-cli "$HOME/.local/bin/solo"
"$HOME/.local/bin/solo" --version
```

Solo fills in the correct bundled binary path for your installation. In this POSIX installation, add `~/.local/bin` to your `PATH` if your shell cannot find `solo`.

Native Windows CLI installation and `PATH` steps are not currently documented; the POSIX snippet above is not native Windows installation guidance.

With the POSIX installation, the installed command is a symlink to the binary inside the app, so it stays current automatically when Solo updates at the same installation path.

## How the CLI finds the app

When the HTTP API is on, Solo writes a discovery file named `http-api.json` into its app data directory. The file records the API's local address, an authentication token, the API version, and the app's process ID. The CLI reads this file, verifies the app is still running, and authenticates every request with the token. You never need to configure a URL or token by hand.

By default the CLI looks in Solo's standard app data directory. If you run Solo with a non-default app data directory, point the CLI at the same place using either:

- The `--app-data-dir <dir>` global flag. `~` and `~/...` paths are supported.
- The `SOLOTERM_APP_DATA_DIR` environment variable.

If the app isn't running, or the discovery file is stale or missing, commands fail with a clear error such as `Solo app is not running, or local CLI access may be off`.

## Global flags

| Flag | Description |
|------|-------------|
| `--json` | Emit machine-readable JSON for API-backed command executions. Help, `--help`, and root `--version` remain human-readable. See [JSON output and scripting](./json-output-and-scripting.md). |
| `--app-data-dir <dir>` | Use this Solo app data directory for discovery. |
| `--help`, `-h` | Show help. |
| `--version`, `-V` | Print the CLI's own version (works without the app running). |

`solo help` shows the full command list, and `solo help <command>` (for example `solo help processes spawn`) shows usage and options for one command. Appending `--help` to any command does the same thing.

## Diagnostics

Three commands help you check the connection between the CLI and the app:

```bash
solo version   # App version and API version, from the running app
solo status    # Snapshot: readiness, project count, process counts, app data dir, port
solo doctor    # Reports CLI version; checks discovery and the live API
```

`solo status` reports whether the app is ready, the API and app versions, how many projects exist, and process counts broken down by state (running, starting, stopping, stopped, exited, failed), plus the app data directory and API port.

`solo doctor` is the first thing to run when something isn't working. It reports the CLI version for context, then loads and validates discovery, requests `/api/version` to verify live API compatibility, and requests `/api/status`. Failures include the underlying reason, but the stage labels do not always identify the exact failing substep. If default discovery fails, it lists every location it tried.

Note the difference between the two version commands: `solo --version` prints the CLI binary's version locally, while `solo version` contacts the running app and reports the app's version.

## Command groups

| Group | Purpose |
|-------|---------|
| `solo projects` | Create, inspect, rename, and delete projects. |
| `solo processes` | Inspect and control individual terminals, commands, and agents. |
| `solo commands` | `start-all` starts trusted commands; `stop-all` stops scoped running commands; `restart-all` stops scoped running commands and starts trusted commands. Batch results report skipped items, including untrusted commands. |
| `solo agents` | List configured [agent tools](../agents/setting-up-tools.md) available for spawning. |
| `solo todos` | List, create, update, complete, and delete project todos. |
| `solo scratchpads` | List, read, create, update, and manage project scratchpads. |

See [Projects and processes](./projects-and-processes.md) and [Todos and scratchpads](./todos-and-scratchpads.md) for the full command reference.

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/cli/overview