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, 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:

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#

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:

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#

See Projects and processes and Todos and scratchpads for the full command reference.