Skip to main content
Version: 0.3 (Next)

CLI Reference

Overview​

The Colony CLI provides commands for bootstrapping management clusters and discovering assets.

Installation​

See Install the CLI for installation instructions.

Commands​

colony init​

Initialize a K3s management cluster with Tinkerbell.

colony init [flags]

Flags:

  • --api-key string - Colony API key (required)
  • --load-balancer-interface string - Network interface for PXE services (required)
  • --load-balancer-ip string - Static IP for Tinkerbell services (required)

Example:

colony init \
  --api-key $COLONY_API_KEY \
  --load-balancer-interface eth0 \
  --load-balancer-ip 192.168.1.10

What it does:

  1. Installs K3s on local machine
  2. Deploys Tinkerbell stack (boots, hegel, rufio, smee, tink-server)
  3. Configures networking for PXE boot
  4. Registers management cluster with Colony API
  5. Starts colony-agent

colony add-ipmi​

Register an asset using IPMI credentials.

colony add-ipmi [flags]

Flags:

  • --ip string - IPMI IP address (required)
  • --username string - IPMI username (required)
  • --password string - IPMI password (required)
  • --auto-discover - Automatically power on and PXE boot asset

Example:

colony add-ipmi \
  --ip 192.168.2.50 \
  --username ADMIN \
  --password secretpass \
  --auto-discover

What it does:

  1. Validates IPMI connectivity
  2. Creates hardware resource in Kubernetes
  3. If --auto-discover: Powers on asset and triggers PXE boot
  4. Asset appears in Colony UI as "discovering"

colony version​

Display Colony CLI version.

colony version

Example output:

Colony CLI version: 0.2.0
Build date: 2024-01-15
Commit: abc123def

colony help​

Display help information.

colony help [command]

Examples:

# General help
colony help

# Command-specific help
colony help init
colony help add-ipmi

Environment Variables​

COLONY_API_KEY​

API key for authentication.

export COLONY_API_KEY="your-api-key-here"
colony init --load-balancer-interface eth0 --load-balancer-ip 192.168.1.10

IPMI_USERNAME / IPMI_PASSWORD​

IPMI credentials for asset discovery.

export IPMI_USERNAME=ADMIN
export IPMI_PASSWORD=secretpass
colony add-ipmi --ip 192.168.2.50 --auto-discover

Exit Codes​

  • 0 - Success
  • 1 - General error
  • 2 - Invalid arguments
  • 3 - Network error
  • 4 - Authentication error

Configuration Files​

~/.colony/config​

K3s kubeconfig created by colony init.

export KUBECONFIG=~/.colony/config
kubectl get pods -A

Tips​

Bulk Asset Discovery​

Use shell loops for multiple assets:

for IP in 192.168.2.{50..60}; do
  colony add-ipmi --ip "$IP" --username ADMIN --password pass --auto-discover
  sleep 5
done

Secure Password Handling​

Avoid exposing passwords:

# Read from stdin
read -s IPMI_PASSWORD
export IPMI_PASSWORD
colony add-ipmi --ip 192.168.2.50 --auto-discover

# Or use a secrets file
source ~/.colony-secrets
colony add-ipmi --ip 192.168.2.50 --auto-discover

What's Next​