cyberwave-cli 0.11.42

The official command-line interface for Cyberwave

Cyberwave CLI

This module is part of Cyberwave: Making the physical world programmable.

The official command-line interface for Cyberwave. Authenticate and bootstrap robotics projects from your terminal.

Installation

From PyPI (pip)

pip install cyberwave-cli

From APT (Debian/Ubuntu)

curl -fsSL https://cyberwave.com/install.sh | bash

From Source

git clone https://github.com/cyberwave-os/cyberwave-cli
cd cyberwave-cli
pip install -e .

Quick Start - Edge

1. SSH into your edge device

ssh yourhost@your-ip

2. Set up your Edge device

Once you are in your edge device, set it up by:

cyberwave edge install

This command will guide you to your first-time setup of your edge device.

Commands

Command	Description
login	Authenticate with Cyberwave
logout	Remove stored credentials
config-dir	Print the active configuration directory
core	Visualize the core commands

cyberwave login

Authenticates with Cyberwave using your email and password.

# Interactive login (prompts for credentials)
cyberwave login

# Non-interactive login
cyberwave login --email [e-mail] --password yourpassword

Options:

• -e, --email: Email address
• -p, --password: Password (will prompt if not provided)

cyberwave config-dir

Prints the resolved configuration directory path. Useful in scripts to locate credentials and config files without hardcoding paths.

cyberwave config-dir
# /etc/cyberwave

# Use in a script
CONFIG_DIR=$(cyberwave config-dir)
cat "$CONFIG_DIR/credentials.json"

The CLI resolves the directory with the following priority:

1. CYBERWAVE_EDGE_CONFIG_DIR environment variable (explicit override)
2. /etc/cyberwave if writable or creatable (system-wide, preferred)
3. ~/.cyberwave as a fallback for non-root users

cyberwave edge

Manage the edge node service lifecycle, configuration, and monitoring.

Subcommand	Description
install	Install cyberwave-edge-core and register systemd service
uninstall	Stop and remove the systemd service
start	Start the edge node
stop	Stop the edge node
restart	Restart the edge node (systemd or process)
status	Check if the edge node is running
pull	Pull edge configuration from backend
whoami	Show device fingerprint and info
health	Check edge health status via MQTT
remote-status	Check edge status from twin metadata (heartbeat)
logs	Show edge node logs
install-deps	Install edge ML dependencies
sync-workflows	Trigger workflow sync on the edge node
list-models	List model bindings loaded on the edge node
driver	Manage edge driver containers (subgroup)

driver subcommand	Description
driver list	List running driver containers (--all includes exited)
driver start	Start a stopped driver container
driver stop	Stop a running driver container

cyberwave edge install

Installs the cyberwave-edge-core package (via apt-get on Debian/Ubuntu) and creates a systemd service so it starts on boot. Guides you through workspace and environment selection.

sudo cyberwave edge install
sudo cyberwave edge install -y   # skip prompts

cyberwave edge uninstall

Stops the systemd service, removes the unit file, and optionally uninstalls the package.

sudo cyberwave edge uninstall

cyberwave edge start / stop / restart

cyberwave edge start                        # background
cyberwave edge start -f                     # foreground
cyberwave edge start --env-file ./my/.env   # custom config

cyberwave edge stop

sudo cyberwave edge restart                 # systemd
cyberwave edge restart --env-file .env      # process mode

cyberwave edge status

Checks whether the edge node process is running.

cyberwave edge status

cyberwave edge pull

Pulls edge configuration from the backend using the discovery API (or legacy twin/environment lookup).

cyberwave edge pull                              # auto-discover via fingerprint
cyberwave edge pull --twin-uuid <UUID>           # single twin (legacy)
cyberwave edge pull --environment-uuid <UUID>    # all twins in environment (legacy)
cyberwave edge pull -d ./my-edge                 # custom output directory

cyberwave edge whoami

Displays the unique hardware fingerprint for this device, used to identify the edge when connecting to twins.

cyberwave edge whoami

cyberwave edge health

Queries real-time health status via MQTT (stream states, FPS, WebRTC connections).

cyberwave edge health -t <TWIN_UUID>
cyberwave edge health -t <TWIN_UUID> --watch     # continuous
cyberwave edge health -t <TWIN_UUID> --timeout 10

cyberwave edge remote-status

Checks the last heartbeat stored in twin metadata to determine online/offline status without MQTT.

cyberwave edge remote-status -t <TWIN_UUID>

cyberwave edge logs

cyberwave edge logs              # last 50 lines
cyberwave edge logs -n 100       # last 100 lines
cyberwave edge logs -f           # follow (tail -f)

cyberwave edge install-deps

Installs common ML runtimes needed by edge plugins.

cyberwave edge install-deps                       # ultralytics + opencv
cyberwave edge install-deps -r onnx -r tflite     # specific runtimes

cyberwave edge sync-workflows / list-models

cyberwave edge sync-workflows --twin-uuid <UUID>  # re-sync model bindings
cyberwave edge list-models --twin-uuid <UUID>      # show loaded models

cyberwave edge driver

Manage edge driver containers.

Subcommand	Description
list	List running driver containers (--all includes exited)
start	Start a stopped driver container
stop	Stop a running driver container

cyberwave edge driver list           # running containers only
cyberwave edge driver list --all     # include exited containers

cyberwave edge driver start                             # interactive picker (stopped containers)
cyberwave edge driver start cyberwave-driver-624d7fe2   # directly by name

cyberwave edge driver stop                              # interactive picker (running containers)
cyberwave edge driver stop cyberwave-driver-624d7fe2    # directly by name

start restarts an existing stopped container and sets a --restart=on-failure Docker policy, so the driver automatically retries if it exits due to a transient error (e.g. robot not yet reachable on the network). To launch a brand-new driver, use the edge-core service which manages image selection and environment configuration.

stop disables the Docker restart policy before stopping, so the container does not come back automatically. If the driver is managed by a systemd service, stop that instead:

sudo systemctl stop cyberwave-video-grabber.service

Configuration

Configuration is stored in a single directory shared by the CLI and the edge-core service. The directory is resolved as follows:

1. CYBERWAVE_EDGE_CONFIG_DIR env var — explicit override
2. /etc/cyberwave — system-wide (preferred, requires root or write access)
3. ~/.cyberwave — per-user fallback for non-root environments

Run cyberwave config-dir to see which directory is active.

Files inside the config directory:

• credentials.json — API token and workspace info (permissions 600)
• environment.json — selected workspace, environment, and twin bindings
• fingerprint.json — unique edge device identifier

Other environment variables:

• CYBERWAVE_BASE_URL: Override the API URL (default: https://api.cyberwave.com)
• CYBERWAVE_ENVIRONMENT: Environment name (for example dev, defaults to production)
• CYBERWAVE_MQTT_HOST: MQTT broker host (for example dev.mqtt.cyberwave.com for dev; defaults to mqtt.cyberwave.com)

When credentials are written, the CLI also persists these CYBERWAVE_* values into credentials.json so cyberwave-edge-core can reuse them in service mode.

Building for Distribution

PyInstaller (standalone binary)

pip install -e ".[build]"
pyinstaller --onefile --name cyberwave-cli cyberwave_cli/main.py

Debian Package

See debian/ directory for packaging scripts.

Contributing

Contributions are welcome. Please open an issue for bugs or feature requests, and submit a pull request for improvements.

Support

• Documentation: docs.cyberwave.com
• Issues: GitHub Issues
• Community: Discord