CLI Command Reference¶

Complete reference for the swarmcracker and swarmctl command-line tools.

swarmcracker¶

The main CLI for cluster management, service deployment, and VM operations.

Global Flags¶

Commands¶

swarmcracker cluster¶

Cluster lifecycle management.

cluster init flags:

cluster join flags:

cluster leave flags: --purge, --force, --keep-network, --state-dir, --bridge-name, --config-dir cluster deinit flags: --purge, --force, --cleanup-network, --keep-tokens, --state-dir, --rootfs-dir, --bridge-name, --config-dir cluster reset flags: --hard, --keep-config, --keep-rootfs, --state-dir, --rootfs-dir, --bridge-name, --config-dir cluster health flags: --format (table, json, nagios), --quiet / -q

swarmcracker node¶

Node management.

node ls flags: --filter, --format (table, json), --quiet / -q. node inspect flags: --format, --pretty.

swarmcracker service¶

Service (replicated microVM) management.

service create flags:

--disk sets a minimum rootfs size. By default the rootfs is sized from the image content plus 50% overhead (floor 100 MB); with --disk 10G it is grown to at least 10 GB, leaving the rest as free space in the guest. The prepared rootfs is keyed by image, so requesting a larger disk rebuilds that image's rootfs (and it is not shrunk again by a later smaller request).

service update flags: --image, --replicas, --cpu-limit, --memory-limit, --env-add, --env-rm, --force / -f. service ls / service ps flags: --filter, --format, --quiet / -q, and --no-trunc for ps.

swarmcracker task¶

Task management.

task ls flags: --all, --filter, --format, --no-trunc, --node, --service, --quiet / -q.

swarmcracker vm¶

Direct Firecracker microVM management.

vm create flags:

vm list flags: --all, --format, --socket-dir. vm logs flags: --follow / -f, --since, --tail. vm stop flags: --force / -f, --timeout. vm attach flags: --socket-dir (default /var/run/firecracker); <vm> is a task ID or any unique prefix. Detach with Ctrl-P Ctrl-Q.

vm list and vm status also cover microVMs started by the daemon for services (discovered from <socket-dir>/*.sock; stale sockets are filtered with a liveness probe). vm stop deliberately refuses to kill a service VM — use swarmcracker service scale <service>=0 or swarmcracker service rm <service> so SwarmKit updates the desired state instead of recreating the task.

swarmcracker network¶

Network management.

swarmcracker volume¶

Persistent volume management.

volume create flags: --type / -t (dir or block), --size / -s (MB), --opt. The --volumes-dir / -d global flag sets the storage directory (default /var/lib/swarmcracker/volumes).

swarmcracker asset¶

Firecracker asset management.

swarmcracker config¶

Configuration management.

swarmcracker setup¶

One-time node setup.

setup install flags: --download-kernel, --download-rootfs, --download-cni, --firecracker-version (default v1.15.1). setup network flags: --bridge, --bridge-ip, --subnet, --nat. setup config flags: --kernel, --rootfs-dir, --bridge, --bridge-ip, --subnet, --vcpus, --memory, --non-interactive.

swarmcracker doctor¶

System and cluster diagnostics.

swarmcracker doctor            # human-readable report
swarmcracker doctor --json     # machine-readable
swarmcracker doctor --verbose  # detailed output

swarmctl¶

Lightweight control-socket client for debugging and manual inspection. It talks directly to the SwarmKit control socket (default /var/run/swarmkit/swarm.sock, override with SWARM_SOCKET), and must run on a manager node.

# Services
swarmctl ls-services
swarmctl create-service nginx:alpine --name web --replicas 2
swarmctl scale <service-id> 3
swarmctl update <service-id> --image nginx:1.25-alpine
swarmctl inspect <service-id|task-id>
swarmctl rm-service <service-id>

# Nodes
swarmctl ls-nodes
swarmctl drain <node-id>
swarmctl activate <node-id>
swarmctl promote <node-id>

# Tasks
swarmctl ls-tasks
swarmctl logs <task-id> --lines 100
swarmctl metrics <task-id>
swarmctl stop-task <task-id>

# Volumes and snapshots
swarmctl volume create <name>
swarmctl volume list
swarmctl snapshot create <task-id>
swarmctl snapshot list
swarmctl snapshot restore <task-id> <snapshot-id>

Deprecated Commands¶

The following legacy commands still work but print a deprecation warning and will be removed in a future release:

Examples¶

Initialize a Cluster¶

sudo swarmcracker cluster init \
    --advertise-addr 192.168.121.155:4242 \
    --vxlan-enabled \
    --vxlan-peers 192.168.121.129,192.168.121.43

Get a Join Token¶

sudo swarmcracker cluster token worker

Join a Worker¶

sudo swarmcracker cluster join 192.168.121.155:4242 \
    --token SWMTKN-1-xxxxx \
    --advertise-addr 192.168.121.129:4242

Deploy a Service¶

swarmcracker service create \
    --name nginx \
    --image nginx:alpine \
    --replicas 2 \
    --cpu 0.5 \
    --memory 256M

Create a VM Directly¶

sudo swarmcracker vm create \
    --name dev-vm \
    --cpu 2 \
    --memory 1024 \
    --detach \
    -e KEY=value \
    alpine:latest

Check Cluster Health¶

sudo swarmcracker cluster health
sudo swarmcracker node ls
sudo swarmcracker doctor

Configuration File¶

See the Configuration Guide for the full config.yaml reference. Default location: /etc/swarmcracker/config.yaml.

version: 1

executor:
  name: firecracker
  kernel_path: /usr/share/firecracker/vmlinux
  rootfs_dir: /var/lib/firecracker/rootfs
  socket_dir: /var/run/firecracker
  default_vcpus: 1
  default_memory_mb: 512
  enable_jailer: false
  init_system: tini      # none | tini | dumb-init

network:
  bridge_name: swarm-br0
  subnet: 192.168.127.0/24
  bridge_ip: 192.168.127.1/24
  ip_mode: static
  nat_enabled: true

images:
  cache_dir: /var/cache/swarmcracker
  max_cache_size_mb: 1024

logging:
  level: info
  format: text
  output: stdout

See Also¶

• Configuration Guide
• API Reference
• Network Reference
• Architecture Overview