CLI Reference

The band CLI is a command-line interface for managing projects, workspaces, tasks, cron jobs, and tunnels. It communicates with the Band server over HTTP and provides both human-readable and machine-readable output formats.

Installation

The CLI is bundled with the Band desktop app. When you install the desktop application, the band binary is placed on your system PATH automatically. No separate installation step is needed.

If you prefer a standalone installation (for example, on a headless server or in CI), you can install the CLI binary directly from the project releases page.

Configuration via Environment Variables

The CLI reads the following environment variables. These override any defaults and are useful in scripted or CI environments.

• BAND_SERVER_URL — Base URL of the Band server. Defaults to http://localhost:3001.
• BAND_TOKEN — Authentication token for remote access. Required when connecting through a tunnel.
• BAND_OUTPUT — Default output format. Set to json for machine-readable output.
• BAND_HOME — Override the Band home directory (defaults to ~/.band).

JSON Output Mode

Every command supports a --output json flag that prints structured JSON instead of the default table or text output. This is useful for scripting and piping into tools like jq.

band projects list --output json
band tasks list --output json | jq '.[0].id'

You can also set BAND_OUTPUT=json in your shell profile to make JSON the default for all commands.

Schema Introspection

The band schema command outputs the full API schema as JSON. This is helpful for building tooling on top of Band or for understanding the available endpoints and their parameters.

band schema

The schema includes all available commands, their arguments, expected input types, and response shapes. Pipe it through jq to explore interactively.

Command Groups

The CLI is organized into the following command groups:

• band projects — Add, list, and remove projects.
• band workspaces — Create, list, and remove workspaces.
• band tasks — Create, list, cancel, rerun, and watch tasks.
• band cronjobs — Schedule recurring tasks with cron expressions.
• band tunnel — Manage Cloudflare tunnel for remote access.
• band settings — View current configuration.

Getting Help

Append --help to any command or subcommand to see usage information, available flags, and examples.

band --help
band projects --help
band tasks create --help