CLI Reference

The umoo-cli binary provides command-line access to the Umoo platform for scripting and automation.

Installation

Build from source:

make build
# Binary: ./bin/umoo-cli

Or copy from a release bundle to a directory in your $PATH.

Configuration

umoo-cli reads configuration from environment variables or flags:

Environment Variable	Flag	Description
UMOO_URL	--url	Server base URL (e.g. https://umoo.yun)
UMOO_TOKEN	--token	JWT access token or API key
UMOO_TENANT_ID	--tenant-id	Tenant UUID

You can also set these in a .env file in the current directory.

Authentication

# Login and store token
umoo-cli auth login --email admin@example.com --password secret

# Show current token info
umoo-cli auth me

Commands

Devices

# List devices
umoo-cli devices list
umoo-cli devices list --group <group-id>
umoo-cli devices list --status online

# Get device detail
umoo-cli devices get <device-id>

# Generate a claim token
umoo-cli device create-claim-token --tenant <tenant-id> --group-id <group-id> --ttl 3600

# Update device
umoo-cli devices update <device-id> --name "new-name" --group <group-id>

Device Groups

# List groups
umoo-cli groups list

# Create group
umoo-cli groups create --name "prod-fleet" --description "Production devices"

# Delete group
umoo-cli groups delete <group-id>

Applications

# List apps
umoo-cli apps list

# Create app
umoo-cli apps create --name nginx --type container

# Create version
umoo-cli apps versions create <app-id> --version 1.0.0 --spec '{"image":"nginx:latest"}'

# List versions
umoo-cli apps versions list <app-id>

Rollouts

# List rollouts
umoo-cli rollouts list
umoo-cli rollouts list --status running

# Get rollout detail
umoo-cli rollouts get <rollout-id>

# Create rollout
umoo-cli rollouts create \
  --name "firmware-v2" \
  --group <group-id> \
  --strategy rolling \
  --batch-size 10 \
  --failure-threshold 20 \
  --target-version '{"firmware":"v2.0.0"}'

# Execute rollout
umoo-cli rollouts execute <rollout-id>

# Pause / resume / cancel
umoo-cli rollouts pause <rollout-id>
umoo-cli rollouts resume <rollout-id>
umoo-cli rollouts cancel <rollout-id>

Shadow State

# Get device shadow
umoo-cli shadow get <device-id>

# Set desired state
umoo-cli shadow set <device-id> '{"apps":{"nginx":{"version":"1.0.0"}}}'

Users

# List users in tenant
umoo-cli users list

# Create user
umoo-cli users create --email user@example.com --password secret --role operator

# Change user role
umoo-cli users set-role <user-id> --role tenant_admin

API Keys

# List API keys
umoo-cli apikeys list

# Generate API key
umoo-cli apikeys generate --name ci-deploy --role operator --expires 2025-12-31

# Revoke API key
umoo-cli apikeys revoke <key-id>

Events

# List events
umoo-cli events list
umoo-cli events list --device <device-id> --type device.online
umoo-cli events list --from 2024-01-01 --to 2024-01-31

Tenants (super admin)

# List all tenants
umoo-cli tenants list

# Create tenant
umoo-cli tenants create --name "Acme Corp"

# Get tenant detail
umoo-cli tenants get <tenant-id>

Roles

# List roles in tenant
umoo-cli role list

# Create custom role
umoo-cli role create --name "deploy-only"

# Delete role
umoo-cli role delete <role-id>

Plugins

# List plugins and their status
umoo-cli plugin list

# Get plugin config
umoo-cli plugin config <plugin-id>

Device Plugin Config

# Get plugin config for a specific device
umoo-cli device-plugin-config get <device-id> <plugin-id>

# Set plugin config override for a device
umoo-cli device-plugin-config set <device-id> <plugin-id> '{"key":"value"}'

SSH Tunneling

# Open an SSH tunnel to a device via the platform
umoo-cli ssh <device-id>
umoo-cli ssh <device-id> --port 22 --user root

VPN

# Connect to a WireGuard network via the platform
umoo-cli vpn connect --network <network-id>

# Disconnect
umoo-cli vpn disconnect

Certificate Management

See Certificate Management for the full umoo cert command reference.

Output Formats

Most list commands support --output flag:

umoo-cli devices list --output json    # JSON array
umoo-cli devices list --output table   # ASCII table (default)
umoo-cli devices list --output yaml    # YAML

Exit Codes

Code	Meaning
0	Success
1	General error
2	Authentication error
3	Permission denied
4	Resource not found

Examples

Deploy an app update across the fleet

# Create a new app version
APP_ID=$(umoo-cli apps list --output json | jq -r '.[] | select(.name=="nginx") | .id')
umoo-cli apps versions create "$APP_ID" --version 1.1.0 --spec '{"image":"nginx:1.25"}'

# Create and execute a rolling rollout
ROLLOUT_ID=$(umoo-cli rollouts create \
  --name "nginx-1.1.0" \
  --group prod-fleet-group-id \
  --strategy rolling \
  --batch-size 5 \
  --failure-threshold 10 \
  --target-version "{\"apps\":{\"nginx\":{\"version\":\"1.1.0\"}}}" \
  --output json | jq -r '.id')

umoo-cli rollouts execute "$ROLLOUT_ID"

# Monitor progress
watch umoo-cli rollouts get "$ROLLOUT_ID"

Register a new device

# Generate a claim token
TOKEN=$(umoo-cli device create-claim-token \
  --tenant "$TENANT_ID" \
  --group-id "$GROUP_ID" \
  --ttl 3600 \
  --output json | jq -r '.token')

# Quick install on the device (as root)
echo "curl -fsSL https://umoo.yun/api/v1/agent/install.sh | CLAIM_TOKEN=$TOKEN sh"