Band Band

band settings

The band settings command prints the live settings.get response from the Band server as pretty-printed JSON. It's a thin pass-through, so the exact shape always matches whatever the server is currently storing in ~/.band/settings.json.

Usage

band settings              # pretty-printed JSON to stdout
band settings --output json # JSON without the trailing newline (for piping)

Example output:

{
  "worktreesDir": "/Users/dev/.band/worktrees",
  "codingAgents": [
    {
      "id": "claude-code",
      "type": "claude-code",
      "label": "Claude Code",
      "command": "claude"
    }
  ],
  "defaultCodingAgent": "claude-code",
  "webServerPort": 3456,
  "notifications": {
    "soundOnNeedsAttention": true
  },
  "labels": [],
  "tokenSecret": "…",
  "autoStartTunnel": false
}

CLI configuration vs. server settings

The command above shows what the server has stored. The band CLI itself reads its connection configuration from environment variables:

  • BAND_SERVER_URL — server URL (default: http://localhost:3456).
  • BAND_TOKEN — auth token. Not needed if the CLI can read it from ~/.band/settings.json.
  • BAND_OUTPUT — default output format, text or json. Equivalent to passing --output on every command.
  • BAND_HOME — alternate Band home directory (default: ~/.band).

Precedence is highest to lowest: command-line flag (--output), environment variable, then built-in default.

Server settings reference

  • worktreesDir — directory where new worktrees are created. Defaults to ~/.band/worktrees.
  • codingAgents — array of agent definitions. Each entry has id, type (claude-code, codex, or opencode), label, and optional command / model overrides.
  • defaultCodingAgent — id of the entry used for new chat panes by default.
  • webServerPort — port the web server listens on (default: 3456).
  • notifications.soundOnNeedsAttention — play a sound when an agent transitions to needs attention.
  • labels — color-coded project labels.
  • tokenSecret — auth token. 64-hex-character string generated on first launch.
  • autoStartTunnel — start the Cloudflare tunnel automatically on server boot.

Troubleshooting

If band settings errors with a connection failure, verify that:

  • The Band desktop app or web server is running.
  • BAND_SERVER_URL points to the correct address and port.
  • No firewall is blocking the connection.
  • If connecting remotely, the tunnel is up and BAND_TOKEN is set.