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:

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:

speedwave --project my-other-project

The CLI commands reference 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 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 for the chat window, the setup wizard, the project switcher, or your first install, since every install needs Desktop at least once.