# Terminal CLI

The `speedwave` command runs Claude Code in your project's containers from a terminal. It's a thin client: it doesn't bundle or manage the container runtime itself, but links the same `speedwave-runtime` library as the Desktop chat app, so a project behaves the same whichever front-end opens it.

## A thin client over Desktop's setup

Before you can use the CLI, install Speedwave Desktop and run its setup wizard once. That single run creates the virtual machine, builds the container images, and configures your tokens; skip it and the CLI has no runtime to drive.

Desktop also installs the CLI for you: the `speedwave` binary ships inside the app and is copied to your `PATH` during setup and on every startup, keeping both on the same version.

`speedwave --help` is the exception: it prints the subcommand list without Desktop running or the runtime installed. Any other command tells you to open Speedwave, finish the Setup Wizard, and start your project if the runtime isn't up.

## Running it

With setup complete, the bare command starts your active project's containers and opens an interactive Claude Code session:

```bash
speedwave
```

The CLI ignores your working directory when picking a project, except for `speedwave init`, which registers the directory you're standing in. It uses the active project recorded in `~/.speedwave/config.json`, the same one the Desktop project switcher set. Pass `--project` to target a different project for one command:

```bash
speedwave --project my-other-project
```

The [CLI commands reference](/docs/reference/cli-commands/) covers every subcommand, project resolution order, and plugin management.

## Two things to know while it's running

A `speedwave` or `speedwave login` session also accepts pasted images, not just Desktop's chat composer. A background watcher polls your clipboard every 250ms and writes any new image to `<project_dir>/.speedwave/pastes/clip.png`, atomically and chmod 0600 on macOS and Linux. No clipboard access just disables it quietly.

When an interactive session ends, the CLI restores your terminal's keyboard, paste, and mouse modes on its own, even after the container or VM went down abnormally, so you no longer need to run `reset` to get a working shell back.

A running CLI session also survives Desktop quitting: the shared VM and containers it's using stay up for the rest of the session. Desktop is still required for OAuth token refresh and the `mcp-os` worker, so if it quits mid-session, OAuth tokens (Slack, SharePoint, GitHub, and similar) pause refreshing and [OS integrations](/docs/integrations/os-integrations/) like mail or calendar go unavailable until Desktop comes back. The CLI logs a warning for each case; the fix is the same either way, start Desktop.

## When to pick it over Desktop

Desktop owns the setup wizard, the project switcher, tray integration, and auto-update checks, and its chat window shows Claude's response as it arrives. The CLI skips all that for Claude Code's own terminal session, with your configured integrations available. Pick the CLI to launch a project from a terminal you already have open, and pick [Desktop](/docs/features/desktop-app/) for the chat window, the setup wizard, the project switcher, or your first install, since every install needs Desktop at least once.
**Tip:** `speedwave --help` always works, even before Desktop is installed or while a setup is broken.