band settings

The band settings command displays the current Band configuration, including server connection details, output format, and home directory paths. This is useful for debugging connection issues or verifying your environment setup.

Usage

band settings

Example output:

Band Settings
─────────────────────────────────────
Server URL:    http://localhost:3001
Home:          /Users/dev/.band
Output:        text
Token:         (not set)
Server:        connected (v0.12.0)

Configuration Sources

Settings are resolved from multiple sources, with the following precedence (highest to lowest):

1. Command-line flags — e.g., --output json on any command.
2. Environment variables — BAND_SERVER_URL, BAND_TOKEN, BAND_OUTPUT, BAND_HOME.
3. Default values — Built-in defaults (server at localhost:3001, text output, home at ~/.band).

Settings Reference

• Server URL — The address of the Band web server. Defaults to http://localhost:3001. Override with BAND_SERVER_URL.
• Home — The Band home directory where worktrees, database, and configuration files are stored. Defaults to ~/.band. Override with BAND_HOME.
• Output — The default output format (text or json). Override with BAND_OUTPUT or --output flag.
• Token — Authentication token for remote server access. Set via BAND_TOKEN. Not needed for local connections.
• Server — Connection status and server version. Shown as "connected" with the version number, or "unreachable" if the server is not running.

JSON Output

band settings --output json

{'{'}
  "serverUrl": "http://localhost:3001",
  "home": "/Users/dev/.band",
  "output": "text",
  "token": null,
  "server": {'{'}
    "status": "connected",
    "version": "0.12.0"
  {'}'}
{'}'}

Troubleshooting

If band settings shows "unreachable" for the server status, verify that:

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