Getting Started

Ready to get started? This guide will walk you through installation, authentication, and provisioning with band.

Install

Homebrew (macOS and Linux):

brew install Bandwidth/tap/band

Go install:

go install github.com/Bandwidth/bw-cli/cmd/band@latest

Pre-built binary: Download the latest release for your OS from GitHub Releases. Binaries are available for macOS, Linux, and Windows.

Docker:

docker run --rm ghcr.io/bandwidth/cli:latest version

From source:

git clone https://github.com/Bandwidth/bw-cli.git
cd bw-cli
make build    # builds ./band
make install  # installs to $GOPATH/bin

Verify the install:

band version

Authenticate

The CLI uses OAuth2 client credentials. Grab your client ID and client secret from The Bandwidth App.

Interactive login:

band auth login

The CLI prompts for your credentials, validates them, and discovers your accessible accounts.

Non-interactive (flags):

band auth login --client-id <id> --client-secret <secret>

Non-interactive (environment variables):

export BW_CLIENT_ID=your-client-id
export BW_CLIENT_SECRET=your-client-secret
band auth login

Check your auth status at any time:

band auth status

Multiple accounts and profiles

If your credentials give you access to multiple accounts:

band auth switch           # interactive selection
band auth switch 9901287   # direct switch by account ID

Profiles let you store separate credentials — useful across environments or roles:

band auth login --profile staging --client-id <id> --client-secret <secret>
band auth profiles          # list all profiles
band auth use staging       # switch active profile

Credentials are stored in your OS keychain. The config file lives at ~/.config/band/config.json.

Run the quickstart

The fastest path to a working setup is one command:

band quickstart

This walks you through creating an application, provisioning a Voice Configuration Package (VCP) or location, and ordering a phone number — all interactively.

Or set up manually

If you prefer to provision step by step, see the use cases guide for complete voice and messaging walkthroughs.

Global flags

These work on every command:

Flag	Description
--format json|table	Output format (default: json)
--plain	Flat JSON — auto-enabled when stdout is piped
--account-id <id>	Override the active account for this command
--environment prod|test	Override the API environment

For help on any command:

band <command> --help