Skip to content
Speedwave

Terminal CLI

The speedwave command-line utility executes Claude Code directly inside your project’s container environment from your preferred terminal emulator. Built on top of the shared speedwave-runtime library, the CLI ensures deterministic container orchestration and model behaviors identical to the Desktop application.

Prerequisites and CLI installation

Section titled “Prerequisites and CLI installation”

The CLI interacts with the virtual machine and container runtime provisioned by Speedwave Desktop. Before utilizing the CLI, complete the initial Desktop Setup Wizard, which initializes the virtual machine, compiles base container images, and configures project token storage.

The speedwave binary is packaged with the desktop application and automatically linked to your system PATH during installation and subsequent updates.

The speedwave --help command functions independently without requiring active background services. All other operational subcommands require an initialized Speedwave environment.

Session invocation and project targeting

Section titled “Session invocation and project targeting”

Once initial setup is complete, executing speedwave initializes the container topology for the active project and starts an interactive Claude Code session:

Terminal window
speedwave

Project resolution defaults to the active project configured in ~/.speedwave/config.json (aligned with the Desktop project switcher). To target a different registered workspace, provide the --project argument:

Terminal window
speedwave --project my-other-project

For the complete list of subcommands, arguments, and configuration flags, consult the CLI commands reference.

Runtime behaviors and session features

Section titled “Runtime behaviors and session features”
  • Clipboard image handling: In interactive CLI sessions (including speedwave and speedwave login), pasting image data is fully supported. A local background monitor detects image buffers and writes content to <project_dir>/.speedwave/pastes/clip.png with 0o600 permissions.
  • Terminal state restoration: Upon session termination or unexpected container restarts, the CLI restores keyboard, mouse, and bracketed paste modes, preventing corrupted terminal states.
  • Service resilience: Active CLI sessions remain operational if the Desktop user interface is closed. Background OAuth token renewal and the mcp-os worker require the Desktop application; if Desktop is closed, OS integrations pause until Desktop is reopened.

Choosing between CLI and Desktop interfaces

Section titled “Choosing between CLI and Desktop interfaces”

The Desktop application provides graphical workspace switching, tray monitoring, automatic updates, and visual chat formatting. The CLI interface is optimized for terminal-centric development and automated scripting. Both interfaces connect to the exact same backend containers and security policies.