CLI commands

This reference documents the complete suite of speedwave command-line subcommands. For an overview of terminal workflows, refer to the CLI feature overview.

Command summary

Command	Description
speedwave [--project <name>]	Initialize container topologies and launch interactive Claude session.
speedwave init [name]	Register the current working directory as an active project.
speedwave login [--project <name>]	Authenticate with Anthropic OAuth.
speedwave logout [--project <name>]	Clear cached Claude session credentials for the project.
speedwave check	Execute runtime prerequisite checks and SecurityCheck audits.
speedwave update [--project <name>]	Recompile modified container images and recreate workspace containers.
speedwave self-update	Download and apply the latest CLI binary release.
speedwave plugin install <path.zip>	Verify and install a cryptographically signed plugin package.
speedwave plugin list	List installed plugins and cryptographic verification states.
speedwave plugin remove <slug>	Remove an installed plugin and associated build artifacts.
speedwave plugin enable <id> --project <name>	Enable a verified plugin for the specified project.
speedwave plugin disable <id> --project <name>	Disable a plugin for the specified project.
speedwave --help / -h / help	Output command usage and exit.

Unrecognized commands output unknown command: '<x>'. Run 'speedwave --help' for usage. Invalid trailing arguments output unexpected argument: '<x>'. Help flags operate without requiring the container daemon to be running.

Project resolution precedence

Commands supporting --project <name> resolve target workspaces using the following order of precedence:

1. The --project <name> or --project=<name> argument passed directly to the command.
2. The active workspace declared in active_project within ~/.speedwave/config.json.
3. The first configured project record if no active project is marked.

If no matching workspace can be resolved, commands terminate with No project configured.

Workspace directories do not dictate active project targeting, with the exception of speedwave init which registers the current directory.

Running speedwave without arguments checks for missing container images, compiling required layers automatically before session launch. It then synchronizes Claude skills and commands, pruning obsolete image tags.

Project registration

Register a workspace with speedwave init. If a project name is omitted, Speedwave derives a slug from the current folder name:

speedwave init          # registers using directory name
speedwave init my-app   # registers under specified identifier

Project identifiers must not exceed 63 characters, must start with an alphanumeric character, and may contain only lowercase letters (a-z), digits (0-9), periods (.), underscores (_), and hyphens (-). If the directory is already registered, init displays the existing project identifier.

Authentication management

speedwave login initializes project containers and triggers claude auth login --claudeai within the container. Interactive browser authentication completes on the host, saving credentials to the project’s persistent claude-home volume.

Before launching authentication, login sets Anthropic as the active provider for the project, cleanly preserving existing third-party endpoint configurations.

speedwave logout purges session tokens (.claude/.credentials.json and .claude.json) from the project’s persistent volume. To remove service credentials associated with plugins, manage credentials via the Desktop interface (see Using plugins).

Security audits and diagnostic checks

speedwave check executes host prerequisite validations alongside SecurityCheck configuration audits, outputting PASS/FAIL status for each rule and returning exit code 0 on success or 1 on failure.

Caution

The CLI performs signature audits on installed plugins prior to running standard commands. If an installed plugin fails signature verification, commands exit with code 2. Recovery can be executed using speedwave plugin remove <slug>, which bypasses startup audits.

Update containers

speedwave update rebuilds container layers whose source inputs have changed and restarts workspace topologies. Upon completion, it reports Updated N containers (M images rebuilt).

Before applying updates, Speedwave generates a configuration snapshot at ~/.speedwave/snapshots/<project>/snapshot.json. If updates encounter failures after container destruction, Speedwave automatically restores the snapshot, rolling back to previous container definitions.

CLI binary upgrades

speedwave self-update retrieves the latest binary release from GitHub Releases, replaces the active executable, and recompiles container images.

When running from within a packaged .app bundle, self-update instructs the user to apply updates via the Desktop application to maintain binary parity. Background checks run at most once per 24 hours, notifying users on stderr when new versions are available.

Plugin management commands

speedwave plugin install ./acme-plugin.zip
speedwave plugin list
speedwave plugin remove <slug>
speedwave plugin enable <service_id> --project acme
speedwave plugin disable <service_id> --project acme

• install: Validates Ed25519 signatures, extracts files to ~/.speedwave/plugins/<slug>/, and compiles container images.
• list: Displays installed plugins alongside [verified] or [UNVERIFIED: <reason>] status flags.
• remove: Deletes plugin packages and runtime state folders.
• enable: Activates verified plugins within a specific project.
• disable: Disables a plugin within a specific project (operates without requiring valid signatures).