CLI Agent Commands | FlightStack

Agent Commands

Manage build agents with the flightstack agent command.

flightstack agent <subcommand> [options]

Commands

list

List all registered agents:

flightstack agent list

Output:

Build Agents (2):
────────────────────────────────────────────────────────────

Mac-Mini-Office
  ID: a1b2c3d4-e5f6-...
  Status: 🟢 Online
  Scope: 🌐 Public
  Platform: macOS
  Capabilities: iOS, Android, Web
  Builds: 127 total, 119 successful

Linux-CI-Server
  ID: f7g8h9i0-j1k2-...
  Status: 🔴 Offline
  Scope: 🔒 Private (Acme Corp)
  Platform: Linux
  Capabilities: Android, Web
  Builds: 45 total, 42 successful

show

Show detailed information about an agent:

flightstack agent show <agent-id>

Output:

Agent Details
────────────────────────────────────────────────────────────
Name: Mac-Mini-Office
ID: a1b2c3d4-e5f6-...
Status: 🟢 Online
Scope: 🌐 Public

System:
  OS: macOS 14.2
  Xcode: 15.1
  Flutter: 3.16.5
  Dart: 3.2.3

Capabilities:
  iOS: ✓
  Android: ✓
  Web: ✓

Statistics:
  Total Builds: 127
  Successful: 119
  Failed: 8
  Avg Build Time: 4.2 min

register

flightstack agent register [options]

Options:

Flag	Description
`--name, -n`	Agent name (default: hostname)
`--org, -o`	Organization ID for private agent

Examples:

# Register with default name
flightstack agent register

# Custom name
flightstack agent register --name "iOS-Builder"

# Private to an organization
flightstack agent register --org abc123-def456

start

Start the build agent:

flightstack agent start [options]

Options:

Flag	Description
`--daemon, -D`	Run in background
`--debug, -d`	Enable debug logging

Examples:

# Foreground (interactive)
flightstack agent start

# Background (daemon)
flightstack agent start --daemon

stop

Stop a running agent:

flightstack agent stop

status

Show local agent status:

flightstack agent status

install

Install agent as a startup service:

flightstack agent install

The agent will start automatically on boot/login.

uninstall

Remove startup service:

flightstack agent uninstall

update

Update an agent’s settings:

flightstack agent update <agent-id> [options]

Options:

Flag	Description
`--name, -n`	New name
`--org, -o`	Move to organization
`--public, -p`	Make public (clear org)

Examples:

# Rename
flightstack agent update abc123 --name "New Name"

# Make public
flightstack agent update abc123 --public

# Assign to organization
flightstack agent update abc123 --org org-id-here

delete

Delete/unregister an agent:

flightstack agent delete <agent-id>

Aliases: unregister

You’ll be prompted for confirmation. If deleting the local agent, configuration files are also removed.

upgrade

Upgrade the agent binary to the latest release. Downloads from the FlightStack release feed, replaces the running binary atomically, and keeps a .backup until success is confirmed.

flightstack agent upgrade [--check]

Options:

Flag	Alias	Description
`--check`	`-c`	Only check for updates; don’t install.

Examples:

# See if a newer version is available
flightstack agent upgrade --check

# Install the latest version
flightstack agent upgrade

Sample output:

FlightStack Agent Upgrade
────────────────────────────────────────
Current version: 1.0.4

✓ Checking for updates… done

New version available: v1.0.5

✓ Downloading…
✓ Extracting…
✓ Installing…

✓ Agent upgraded to v1.0.5

If the agent is running, restart it to use the new version.

If the agent is running as a service, restart it after upgrade — flightstack agent stop followed by flightstack agent start --daemon, or use your service manager (launchctl kickstart, systemctl --user restart).

doctor

Diagnose common agent issues — registration, service installation, binary version, running process, plist path (macOS), and API connectivity.

flightstack agent doctor

Sample output:

FlightStack Agent Doctor
══════════════════════════════════════════════════

[Agent Registration]
  ✓ Registered as macbook-pro
  Agent ID: a1b2c3d4-…

[Service Installation]
  ✓ Service file found
  Path: ~/Library/LaunchAgents/com.voostack.flightstack-agent.plist

[Service Binary Version]
  ✓ Version: 1.0.5
  ✓ Build: 4f4a17

[Agent Process]
  ✓ Agent running (PID: 7124)

[Service Path]
  ✓ Service path is stable

[API Connectivity]
  ✓ API reachable (https://api.flightstack.voostack.com)

══════════════════════════════════════════════════
✓ No issues found!

Use this first when a build agent stops picking up jobs — it surfaces version mismatches, stale PID files, and broken Homebrew Cellar paths automatically.