Band Band

CLI Reference

The band CLI is a command-line interface for managing projects, workspaces, chat panes, terminals, browser tabs, cronjobs, and tunnels. It communicates with the Band server over HTTP and provides both human-readable and JSON output.

Installation

The CLI is bundled with the Band desktop app. On first launch the desktop app prompts to install a /usr/local/bin/band symlink (admin password required). After that the band command is on your PATH in every shell.

For headless installs (CI, remote servers) you can build the CLI from source with cargo build --release --manifest-path apps/cli/Cargo.toml.

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:3456.
  • BAND_TOKEN — Authentication token for remote access. Required when connecting through a tunnel; on the local machine the CLI reads it from ~/.band/settings.json automatically.
  • 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 chats list --output json | jq '.chats[].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 CLI command schema as JSON. This is helpful for building tooling on top of Band or for understanding the available commands and their parameters. 

band schema                       # all commands
band schema "workspaces create"   # one command's schema

The schema includes every command, its positional arguments, named flags, types, and required/optional metadata. Pipe it through jq to explore interactively.

Command groups

The CLI is organized into the following command groups:

  • band projects — Register and unregister projects.
  • band workspaces — Create and remove workspaces (Git worktrees).
  • band chats — Send messages to coding agents and manage chat panes.
  • band terminals — Manage PTY-backed terminal sessions inside a workspace.
  • band browsers — Manage browser tabs inside a workspace.
  • band cronjobs — Schedule recurring agent tasks with cron expressions.
  • band tunnel — Start, stop, and inspect the Cloudflare tunnel.
  • band settings — Print the live server settings as JSON.
  • band notify — Hook target invoked by Claude Code; reads JSON from stdin and reports agent status. Wired up automatically on first launch.
  • band schema — Print the CLI command schema as JSON.
  • band generate-skills — Regenerate the four SKILL.md files in apps/cli/skills/ from the templates plus the schema.

Getting help

Append --help to any command or subcommand to see usage, flags, and a one-line description. 

band --help
band projects --help
band chats send --help