wavectl CLI Reference¶

Complete command-line reference for managing Waveshift infrastructure. For deployment workflows and detailed examples, see the Quick Start Guide and Installation Guide.

Overview¶

wavectl provides complete lifecycle management for Waveshift infrastructure:

Infrastructure Deployment - Deploy AWS infrastructure (VPC, EC2, IAM, DNS)
Access Server Management - Deploy and manage WireGuard access servers
Site Management - Register and manage sites via API
Hub Router Configuration - Configure hub routers via SSH
Session Management - Start AWS SSM sessions to instances
Proxy Management - Port forwarding to Waveshift console

Prerequisites

See the Installation Guide for prerequisites and setup requirements.

Configuration¶

wavectl.json¶

Primary configuration file created by wavectl init. All commands read AWS profile, region, and infrastructure state from this file.

Key Benefits:

One-time AWS configuration during wavectl init
All commands use consistent AWS profile/region
No need to specify --profile or --region flags repeatedly
Persistent infrastructure state

Global Options¶

Option	Description
`--help`	Show help information for any command

Usage: wavectl <command> --help

Commands¶

wavectl init¶

Initialize wavectl.json configuration file.

Synopsis:

wavectl init --identity-provider <provider> [options]

Options:

Option	Type	Description	Default
`--identity-provider`	string	GCP workload identity provider (required)	-
`--region`	string	AWS region	Auto-detected
`--profile`	string	AWS profile to use	-
`--kasm-instance-type`	string	Kasm EC2 instance type	`m6a.2xlarge`

Examples:

# Basic initialisation
wavectl init --identity-provider my-provider --profile my-profile --region eu-west-2

# With custom Kasm instance type
wavectl init --identity-provider my-provider --profile my-profile --kasm-instance-type t3a.medium

# Auto-detect region from AWS profile
wavectl init --identity-provider my-provider --profile my-profile

One-Time Setup

Run init once per deployment. All subsequent commands use this configuration.

wavectl deploy¶

Deploy complete AWS infrastructure.

Synopsis:

wavectl deploy [options]

Deploys: - VPC with public/private subnets - Internet Gateway and NAT Gateway - Security Groups and IAM roles - EC2 instances (Waveshift controller, Kasm) - Route53 hosted zone and DNS records - SSM Parameter Store configuration

Options:

Option	Type	Description	Default
`--skip-aws-check`	bool	Skip AWS connectivity check	`false`
`--destroy`	string	Destroy infrastructure (`all`)	-

Examples:

# Deploy infrastructure
wavectl deploy

# Skip AWS connectivity check
wavectl deploy --skip-aws-check

# Destroy all infrastructure
wavectl deploy --destroy all

Deployment Time

Typical deployment takes 10-15 minutes.

Destroy Operation

--destroy all permanently deletes all AWS resources.

wavectl access-servers¶

Manage WireGuard access server infrastructure.

Synopsis:

wavectl access-servers [options]

Options:

Option	Type	Description	Default
`--add`	int	Number of access servers to add	-
`--destroy`	string	Destroy servers (`all` or server number)	-
`--wg-config`	int	Generate WireGuard config for server	-
`--interactive`	bool	Interactive mode	`true`

Examples:

# Add 2 access servers
wavectl access-servers --add 2

# Generate WireGuard config for server 0
wavectl access-servers --wg-config 0

# Destroy specific server
wavectl access-servers --destroy 1

# Destroy all servers
wavectl access-servers --destroy all

WireGuard Config

Generated config saved as waveshift-access-N.conf in current directory.

Single Connection

Only ONE device can use each access server config at a time.

wavectl sites¶

Manage site configurations and registrations.

Synopsis:

wavectl sites [options]

Operations: - Registers sites with Waveshift API - Assigns sites to access servers sequentially - Includes automatic health check before registration - Does NOT create EC2 instances (use access-servers)

Options:

Option	Type	Description	Default
`--add`	int	Number of sites to register	-
`--deregister`	string	Deregister site (`all` or site number)	-
`--interactive`	bool	Interactive mode	`true`

Examples:

# Register 2 sites
wavectl sites --add 2

# Deregister site 1
wavectl sites --deregister 1

# Deregister all sites
wavectl sites --deregister all

Health Check

Command performs health check before registration. May take up to 15 minutes if run immediately after deploy.

Access Servers Required

Must have access servers deployed before registering sites.

wavectl configure-hub¶

Configure GL.iNet routers as Waveshift hub devices.

Synopsis:

wavectl configure-hub [options]

Configures: - Network settings (LAN IP, WireGuard) - DHCP configuration - Device scanner script - System time synchronisation

Options:

Option	Type	Description	Default
`--site`	int	Site number to configure	Interactive if not specified
`--site-id`	string	Optional site ID UUID	Auto-detected
`--ssh-user`	string	SSH username	`root`
`--ssh-password`	string	SSH password	`Waveshift2025!`
`--interactive`	bool	Interactive mode	Auto if no site specified

Examples:

# Configure hub for site 0
wavectl configure-hub --site 0

# Configure hub for site 1
wavectl configure-hub --site 1

# Interactive mode
wavectl configure-hub --interactive

Prerequisites

Router must be flashed with Waveshift firmware
Router must be physically connected to your device
Only configure ONE hub per site

Router Reboot

Router will reset and reboot after configuration (indicated by LED).

wavectl proxy¶

Start SSM port forwarding proxy to Waveshift console.

Synopsis:

wavectl proxy [options]

Provides: - Local access to Waveshift console at http://localhost:8080 - No WireGuard or hub connection required - Uses AWS SSM port forwarding

Options:

Option	Type	Description	Default
`--local-port`	string	Local port for proxy	`8080`
`--remote-port`	string	Remote port on instance	`80`

Examples:

# Start proxy (default port 8080)
wavectl proxy

# Custom local port
wavectl proxy --local-port 9090

# Run in background
wavectl proxy &

# Stop background proxy
pkill -f "wavectl proxy"

Quick Access

Fastest way to access Waveshift console without WireGuard or hub setup.

wavectl start-session¶

Start AWS SSM session to infrastructure components.

Synopsis:

wavectl start-session <server_name>

Available Servers:

Server Name	Description
`waveshift`	Main Waveshift controller
`kasm`	Kasm workspace instance
`access_server_N`	Access server N (e.g., `access_server_0`)

Examples:

# Connect to Waveshift controller
wavectl start-session waveshift

# Connect to Kasm workspace
wavectl start-session kasm

# Connect to access server 0
wavectl start-session access_server_0

# Connect to access server 1
wavectl start-session access_server_1

Secure Shell Access

Provides shell access without requiring direct SSH or bastion hosts.

Common Workflows¶

For complete deployment workflows, see:

Quick Start Guide - Command-focused scenarios
Installation Guide - Detailed step-by-step guide

Typical Deployment Order¶

1. wavectl init                      # Configure AWS settings
2. wavectl deploy                    # Deploy infrastructure (~10-15 mins)
3. wavectl access-servers --add N    # Create access servers
4. wavectl sites --add N             # Register sites (includes health check)
5. wavectl configure-hub --site 0    # Configure routers

Quick Access¶

# Access console via proxy
wavectl proxy

# SSH to controller
wavectl start-session waveshift

# Get WireGuard config
wavectl access-servers --wg-config 0

Error Handling¶

wavectl provides comprehensive error messages:

Dependency Validation - Checks for AWS CLI and Session Manager Plugin
Configuration Validation - Ensures wavectl.json exists
AWS Connectivity - Validates credentials and region
Resource Validation - Prevents invalid operations
Clear Error Messages - Actionable guidance for resolution

Troubleshooting¶

Quick Diagnostics:

# Verify AWS setup
aws sts get-caller-identity

# Check configuration
cat wavectl.json

# Test connectivity
wavectl proxy

Detailed Help

For comprehensive troubleshooting, see:

Quick Start Troubleshooting - Common command issues
Troubleshooting Guide - Detailed solutions

Exit Codes¶

All wavectl commands return:

0 - Success
1 - Error (with descriptive message)

wavectl CLI Reference¶

Overview¶

Configuration¶

wavectl.json¶

Global Options¶

Commands¶

wavectl init¶

wavectl deploy¶

wavectl access-servers¶

wavectl sites¶

wavectl configure-hub¶

wavectl proxy¶

wavectl start-session¶

Common Workflows¶

Typical Deployment Order¶

Quick Access¶

Error Handling¶

Troubleshooting¶

Exit Codes¶

See Also¶