### Run Interactive Quickstart Wizard

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Initiate the interactive setup wizard for new users. This guides through login, account selection, and initial voice or message setup.

```bash
band quickstart
```

--------------------------------

### Install via Go

Source: https://github.com/bandwidth/cli/blob/main/README.md

Installs the Bandwidth CLI using the Go programming language's install command.

```sh
go install github.com/Bandwidth/cli/cmd/band@latest
```

--------------------------------

### Spinner Usage Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Demonstrates how to create, start, and stop a spinner for a task, followed by a success message. This pattern is useful for providing visual feedback during operations.

```go
spin := ui.NewSpinner("Verifying credentials...")
spin.Start()
// ... do work ...
spin.Stop()
u.Successf("Credentials verified")
```

--------------------------------

### Multi-Environment Setup Usage

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/configuration.md

Commands demonstrating how to switch between environments and execute commands specific to each, such as testing and production.

```bash
# Test environment
band auth use test
band call create --from +19195551234 --to +15559876543 --app-id test-app --answer-url https://example.com/voice

# Switch back to production
band auth use prod
band call create --from +19195551234 --to +15559876543 --app-id prod-app --answer-url https://example.com/voice
```

--------------------------------

### CI/CD Environment Setup with Environment Variables

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/configuration.md

Setup for CI/CD environments using environment variables for credentials and environment. Alternatively, login can be performed using client ID and secret.

```bash
#!/bin/bash
export BW_CLIENT_ID=CLI-ci-abc123
export BW_CLIENT_SECRET=super-secret-from-vault
export BW_ACCOUNT_ID=9901234
export BW_ENVIRONMENT=prod

# Or set it once in config
band auth login --client-id CLI-ci-abc123 --client-secret super-secret
```

--------------------------------

### One-Command Legacy Setup

Source: https://github.com/bandwidth/cli/blob/main/README.md

This command provides a simplified, one-command approach to setting up a legacy Bandwidth account. It requires specifying the callback URL. This is an alternative to running individual setup commands.

```sh
band quickstart --callback-url <url> --legacy
```

--------------------------------

### Go Cobra Get Command Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/command-structure.md

This snippet shows the implementation of a 'get' command for retrieving a specific resource by its ID. It requires a resource ID as an argument.

```go
var getCmd = &cobra.Command{
    Use:   "get <resource-id>",
    Short: "Get a resource",
    Args:  cobra.ExactArgs(1),
    RunE: func(cmd *cobra.Command, args []string) error {
        client, acctID, err := cmdutil.VoiceClient(cmdutil.AccountIDFlag(cmd))
        if err != nil {
            return err
        }
        
        resourceID := args[0]
        var result interface{}
        if err := client.Get(fmt.Sprintf("/accounts/%s/resources/%s", acctID, resourceID), &result); err != nil {
            return err
        }
        
        format, plain := cmdutil.OutputFlags(cmd)
        return output.StdoutAuto(format, plain, result)
    },
}
```

--------------------------------

### List all locations

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Use this command to list all account locations. No setup is required beyond having the CLI installed.

```bash
band location list
```

--------------------------------

### Example: Building a Voice Client

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Demonstrates how to build a Voice API client using `cmdutil.AccountIDFlag` and `cmdutil.VoiceClient`, then making an API call.

```go
import (
    "github.com/Bandwidth/cli/internal/cmdutil"
    "github.com/spf13/cobra"
)

func runVoiceCommand(cmd *cobra.Command, args []string) error {
    // Get the account ID (from flag, env, or config)
    accountIDOverride := cmdutil.AccountIDFlag(cmd)
    
    // Build the Voice API client
    client, accountID, err := cmdutil.VoiceClient(accountIDOverride)
    if err != nil {
        return err
    }
    
    // Make an API call
    var result interface{}
    err = client.Get("/accounts/"+accountID+"/calls", &result)
    return err
}
```

--------------------------------

### Install via Homebrew

Source: https://github.com/bandwidth/cli/blob/main/README.md

Installs the Bandwidth CLI on macOS and Linux systems using the Homebrew package manager.

```sh
brew install Bandwidth/tap/band
```

--------------------------------

### Register a Bandwidth Account

Source: https://github.com/bandwidth/cli/blob/main/README.md

Use this command to start a free trial account with Bandwidth. This is the first step for new users.

```sh
band account register
```

--------------------------------

### Verify Bandwidth CLI Setup

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/README.md

Check the active account and profile, list available applications, and list phone numbers associated with your account.

```bash
band auth status              # Check active account and profile
band app list                 # List applications
band number list              # List phone numbers
```

--------------------------------

### Multi-Environment Setup Configuration

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/configuration.md

Configuration for managing multiple environments (e.g., production and testing) within the same setup.

```json
{
  "active_profile": "prod",
  "profiles": {
    "prod": {
      "client_id": "CLI-prod",
      "account_id": "9901234",
      "environment": "prod"
    },
    "test": {
      "client_id": "CLI-test",
      "account_id": "9901235",
      "environment": "test"
    }
  }
}
```

--------------------------------

### CLI Configuration Hint Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/configuration.md

This is an example of a contextual hint printed to stderr when CLI configuration is ambiguous, such as multiple accounts or profiles being available. It indicates the current account, profile, and environment.

```bash
[account: 9901234 | profile: prod | env: test]
```

--------------------------------

### CLI Configuration Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Demonstrates loading configuration, accessing the active profile with environment overlays, creating and storing a new profile, and saving the updated configuration back to the file. Note that `ActiveProfileConfig()` returns a fresh copy with environment variable overlays applied.

```go
import "github.com/Bandwidth/cli/internal/config"

// Load config
path, _ := config.DefaultPath()
cfg, _ := config.Load(path)

// Get active profile with env overlays
profile := cfg.ActiveProfileConfig()
fmt.Println(profile.AccountID)  // Active account, respecting BW_ACCOUNT_ID

// Create and store a new profile
cfg.SetProfile("staging", &config.Profile{
    ClientID:    "CLI-staging",
    AccountID:   "9901235",
    Environment: "test",
})

// Save back to file
config.Save(path, cfg)
```

--------------------------------

### Send a Message (Example)

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

An example of sending a message with specific sender and recipient numbers, application ID, and text content. The output will be JSON containing message ID and segment count.

```bash
band message send --from +19195551234 --to +15559876543 --app-id abc-123 --text "Hello from the agent"
```

--------------------------------

### Go Cobra List Command Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/command-structure.md

This snippet demonstrates how to implement a 'list' command using Cobra. It fetches all resources for a given account and outputs them.

```go
var listCmd = &cobra.Command{
    Use:   "list",
    Short: "List all resources",
    RunE: func(cmd *cobra.Command, args []string) error {
        client, acctID, err := cmdutil.VoiceClient(cmdutil.AccountIDFlag(cmd))
        if err != nil {
            return err
        }
        
        var result interface{}
        if err := client.Get(fmt.Sprintf("/accounts/%s/resources", acctID), &result); err != nil {
            return err
        }
        
        format, plain := cmdutil.OutputFlags(cmd)
        return output.StdoutAuto(format, plain, result)
    },
}
```

--------------------------------

### Bandwidth CLI Configuration Hierarchy Examples

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/README.md

Demonstrates equivalent ways to set the account ID for a 'call create' command using CLI flags, environment variables, or a configuration file.

```bash
# All three of these are equivalent:
band call create ... --account-id 9901234
BW_ACCOUNT_ID=9901234 band call create ...
# (with 9901234 set in config.json and no flag/env override)
```

--------------------------------

### Example: Voice API Call with JSON

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Demonstrates creating a JSON API client and making a POST request to initiate a voice call. Handles potential API errors.

```go
import "github.com/Bandwidth/cli/internal/api"

tm := auth.NewTokenManager(clientID, clientSecret, "https://api.bandwidth.com")
client := api.NewClient("https://voice.bandwidth.com/api/v2", tm)

// Create a call
requestBody := map[string]string{
    "from":          "+19195551234",
    "to":            "+15559876543",
    "applicationId": "app-123",
    "answerUrl":     "https://example.com/voice",
}

var response interface{}
err := client.Post("/accounts/9901234/calls", requestBody, &response)
if err != nil {
    // Handle error (check for *api.APIError)
}
// response is now a map[string]interface{} with call details
```

--------------------------------

### Progress Spinner Usage

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/types.md

Demonstrates how to create, start, and stop a progress spinner for long-running operations.

```go
spin := ui.NewSpinner("Verifying credentials...")
spin.Start()
// ... do work ...
spin.Stop()
```

--------------------------------

### Example: Dashboard API Call with XML

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Shows how to use `NewXMLClient` and wrap request data in `api.XMLBody` for making POST requests to the Dashboard API.

```go
import "github.com/Bandwidth/cli/internal/api"

tm := auth.NewTokenManager(clientID, clientSecret, "https://api.bandwidth.com")
client := api.NewXMLClient("https://api.bandwidth.com/api/v2", tm)

// Create an application
err := client.Post("/accounts/9901234/applications", api.XMLBody{
    RootElement: "Application",
    Data: map[string]interface{}{
        "ServiceType": "Voice-V2",
        "AppName":     "My App",
        "CallInitiatedCallbackUrl": "https://example.com/voice",
    },
}, &response)
```

--------------------------------

### Version Check Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Shows how to use the `version.Check` function to determine if an update is available and print a notice message if one exists. Ensure the `fmt` package is imported for printing.

```go
import "github.com/Bandwidth/cli/internal/version"

result := version.Check("0.1.0")
if result != nil {
    fmt.Println(result.NoticeMessage())
}
```

--------------------------------

### Register a New Bandwidth Account

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

Use this command to initiate account registration when no credentials exist. The CLI submits the request, and the remaining setup, including email verification, OTP confirmation, password setting, and OAuth2 credential generation, must be completed in the browser. This flow requires human intervention to finish.

```bash
band account register --phone +19195551234 --email you@example.com --first-name Jane --last-name Doe --accept-tos
```

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

```bash
band auth status   # confirm
```

--------------------------------

### Store, Retrieve, and Delete Keychain Credentials Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Demonstrates the usage of storing, retrieving, and deleting credentials from the OS keychain using the internal auth package.

```Go
// Store client secret
auth.StorePassword("CLI-abc123", "my-secret")

// Retrieve it later
secret, err := auth.GetPassword("CLI-abc123")

// Delete it
auth.DeletePassword("CLI-abc123")
```

--------------------------------

### Example: Printing API Responses

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Demonstrates how to use the output package to print data to stdout in JSON, table, or flattened JSON formats. Ensure necessary packages like 'os' and 'github.com/Bandwidth/cli/internal/output' are imported.

```go
import (
    "github.com/Bandwidth/cli/internal/output"
    "os"
)

data := map[string]interface{}{
    "id":   "call-123",
    "state": "answered",
}

// Print to stdout as JSON
output.StdoutAuto("json", false, data)

// Print to stdout as table
output.Print(os.Stdout, "table", data)

// Print flattened JSON (for scripts)
output.StdoutAuto("json", true, data)
```

--------------------------------

### Example Usage of PollConfig

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/types.md

Demonstrates how to use `PollConfig` to set up polling for an operation, including defining the interval, timeout, and a custom check function.

```go
result, err := cmdutil.Poll(cmdutil.PollConfig{
    Interval: 2 * time.Second,
    Timeout:  120 * time.Second,
    Check: func() (bool, interface{}, error) {
        // Call API to check status
        state, err := getCallState(callID)
        return state.IsTerminal(), state, err
    },
})
```

--------------------------------

### Inspect Bandwidth CLI Resources

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

Use `get` commands to retrieve the current state of resources such as calls, applications, or phone numbers.

```bash
band call get <call-id>
```

```bash
band app get <app-id>
```

```bash
band number get +19195551234
```

--------------------------------

### Send Bandwidth message with media content

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

This example demonstrates sending a message with media content, fulfilling the requirement of having either `--text` or `--media`.

```bash
# Or add media
band message send --to +15551234567 --from +15559876543 --app-id abc --media https://example.com/image.png
```

--------------------------------

### Go CLI Command Structure Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/command-structure.md

This Go code demonstrates the typical structure of a command in the Bandwidth CLI using the Cobra library. It includes definitions for global flags, parent commands, leaf commands, and the execution logic for a command handler.

```go
package domain

import "github.com/spf13/cobra"

// Global flags for this command
var (
    flagName1 string
    flagName2 bool
    flagName3 int
)

// Subcommand (if a parent command)
var Cmd = &cobra.Command{
    Use:   "domain",
    Short: "Short description",
    Long:  "Longer description",
}

func init() {
    // Register subcommands
    Cmd.AddCommand(subcommand1)
    Cmd.AddCommand(subcommand2)
}

// Leaf command
var leafCmd = &cobra.Command{
    Use:     "action",
    Short:   "Short description",
    Long:    "Longer description",
    Example: "# Example usage\nband domain action --flag value",
    RunE:    runAction,  // RunE for error handling
}

func init() {
    // Register flags
    leafCmd.Flags().StringVar(&flagName1, "flag-name", "", "Description")
    leafCmd.Flags().BoolVar(&flagName2, "flag-name", false, "Description")
    
    // Mark required flags
    _ = leafCmd.MarkFlagRequired("flag-name")
    
    // Add to parent
    Cmd.AddCommand(leafCmd)
}

// Option struct (optional, for readability)
type ActionOpts struct {
    Field1 string
    Field2 bool
}

// Validation function (optional)
func ValidateActionOpts(opts ActionOpts) error {
    if opts.Field1 == "" {
        return fmt.Errorf("field1 is required")
    }
    return nil
}

// Build request body helper (optional)
func BuildActionBody(opts ActionOpts) map[string]interface{} {
    return map[string]interface{}{
        "field1": opts.Field1,
    }
}

// Command handler
func runAction(cmd *cobra.Command, args []string) error {
    // 1. Get authentication and client
    client, acctID, err := cmdutil.VoiceClient(cmdutil.AccountIDFlag(cmd))
    if err != nil {
        return err
    }
    
    // 2. Validate input
    opts := ActionOpts{Field1: flagName1}
    if err := ValidateActionOpts(opts); err != nil {
        return err
    }
    
    // 3. Make API request
    body := BuildActionBody(opts)
    var result interface{}
    if err := client.Post(fmt.Sprintf("/accounts/%s/resource", acctID), body, &result); err != nil {
        return fmt.Errorf("creating resource: %w", err)
    }
    
    // 4. Handle async operations (if applicable)
    if flagWait {
        final, err := cmdutil.Poll(cmdutil.PollConfig{
            Interval: 2 * time.Second,
            Timeout:  flagTimeout,
            Check: func() (bool, interface{}, error) {
                // Polling logic
            },
        })
        if err != nil {
            return err
        }
        result = final
    }
    
    // 5. Output result
    format, plain := cmdutil.OutputFlags(cmd)
    return output.StdoutAuto(format, plain, result)
}

```

--------------------------------

### Create Bandwidth voice application

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

When creating an application, the `--type` flag must be set to 'voice' or 'messaging'. This example shows creating a voice application.

```bash
band app create --name "My App" --type voice --callback-url https://example.com/voice
```

--------------------------------

### Run Docker Image

Source: https://github.com/bandwidth/cli/blob/main/README.md

Executes the latest Bandwidth CLI Docker image to check its version. Useful for verifying the Docker setup.

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

--------------------------------

### Get Universal Platform v2 Client

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Obtains the Universal Platform v2 client. An account ID override can be provided.

```go
// Get Universal Platform v2 client
func PlatformClient(accountIDOverride string) (*api.Client, string, error)
```

--------------------------------

### Config Methods

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Includes methods to retrieve the active profile with environment variable overlays applied, store and set a profile, get a sorted list of profile names, and check if profiles span multiple environments.

```go
// Get the active profile with BW_* environment overlays applied
func (c *Config) ActiveProfileConfig() *Profile

// Store a profile and set it as active
func (c *Config) SetProfile(name string, p *Profile)

// Get sorted list of profile names
func (c *Config) ProfileNames() []string

// Check if profiles span multiple environments
func (c *Config) HasMultipleEnvironments() bool
```

--------------------------------

### Go Cobra Create Command Example with Idempotence

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/command-structure.md

This snippet implements a 'create' command that can optionally skip creation if the resource already exists. It requires a resource name and supports an 'if-not-exists' flag.

```go
var createCmd = &cobra.Command{
    Use:   "create",
    Short: "Create a resource",
    RunE: func(cmd *cobra.Command, args []string) error {
        client, acctID, err := cmdutil.VoiceClient(cmdutil.AccountIDFlag(cmd))
        if err != nil {
            return err
        }
        
        if createIfNotExists {
            // Check if resource already exists
            var list interface{}
            if err := client.Get(fmt.Sprintf("/accounts/%s/resources", acctID), &list); err == nil {
                if existing := output.FindByName(list, "Name", createName); existing != nil {
                    format, plain := cmdutil.OutputFlags(cmd)
                    return output.StdoutAuto(format, plain, existing)
                }
            }
        }
        
        // Create the resource
        body := BuildCreateBody(CreateOpts{Name: createName})
        var result interface{}
        if err := client.Post(fmt.Sprintf("/accounts/%s/resources", acctID), body, &result); err != nil {
            return err
        }
        
        format, plain := cmdutil.OutputFlags(cmd)
        return output.StdoutAuto(format, plain, result)
    },
}

func init() {
    createCmd.Flags().StringVar(&createName, "name", "", "Resource name (required)")
    createCmd.Flags().BoolVar(&createIfNotExists, "if-not-exists", false, "Skip if already exists")
    _ = createCmd.MarkFlagRequired("name")
}
```

--------------------------------

### Example Usage of XMLBody for POST Request

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/types.md

Demonstrates how to use the XMLBody struct to send an XML-formatted request body for creating a new application via a POST request.

```go
client.Post("/accounts/123/applications", api.XMLBody{
    RootElement: "Application",
    Data: map[string]interface{}{
        "AppName": "My App",
    },
}, &result)
```

--------------------------------

### Config Loading and Saving Functions

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Provides functions to get the default configuration file path, load configuration from a file (with defaults if the file is missing), and save configuration to a file, creating parent directories as needed.

```go
// Get the default config file path (~/.config/band/config.json or legacy ~/.band/config.json)
func DefaultPath() (string, error)

// Load config from file (returns defaults if file doesn't exist)
func Load(path string) (*Config, error)

// Save config to file (creates parent directories as needed)
func Save(path string, cfg *Config) error
```

--------------------------------

### Example: Polling with --wait

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Illustrates how to use `cmdutil.Poll` with a custom check function to poll an API endpoint until a specific state is reached or a timeout occurs.

```go
import (
    "github.com/Bandwidth/cli/internal/cmdutil"
    "time"
)

result, err := cmdutil.Poll(cmdutil.PollConfig{
    Interval: 2 * time.Second,
    Timeout:  120 * time.Second,
    Check: func() (bool, interface{}, error) {
        // Call API to check status
        var state interface{}
        if err := client.Get("/accounts/"+accountID+"/calls/"+callID, &state); err != nil {
            return false, nil, err
        }
        
        // Check if operation is complete
        m := state.(map[string]interface{})
        if m["state"] == "disconnected" {
            return true, state, nil  // Done!
        }
        return false, nil, nil  // Not done, keep polling
    },
})

if err != nil {
    // Could be ErrPollTimeout or an API error
    return err
}

// result now has the final state
```

--------------------------------

### Scripting with --plain and jq

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/README.md

Combine the --plain output format with tools like `jq` for powerful data manipulation in scripts. This example filters answered calls from a list.

```bash
band call list --plain | jq '.[] | select(.state == "answered")'
```

--------------------------------

### Provision Voice from Scratch (Universal Platform)

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

Step-by-step commands to provision voice services using the Universal Platform. Ensure you have the necessary callback URL and app ID.

```bash
band auth status                                                                    # 1. verify auth
band app create --name "Agent Voice" --type voice --callback-url <url> --if-not-exists --plain  # 2. create app
band vcp create --name "Agent VCP" --app-id <app-id> --if-not-exists --plain        # 3. create VCP linked to app
band number list --plain                                                            # 4. check existing numbers
# if no numbers:
band number search --area-code 919 --quantity 1 --plain
band number order <number> --subaccount <subaccount-id> --wait                                                   # 5. order number
band vcp assign <vcp-id> <number>                                                   # 6. assign number to VCP
band number activate <number> --voice-inbound --wait                                # 7. enable inbound voice
```

--------------------------------

### Send Bandwidth message with text content

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

When sending a message, at least one of `--text` or `--media` is required. This example shows how to include text content.

```bash
# Add text
band message send --to +15551234567 --from +15559876543 --app-id abc --text "Hello"
```

--------------------------------

### Get Recording Metadata

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve metadata for a specific recording by its ID. This command is useful for getting information about a recording before downloading it.

```bash
band recording get <recording-id>
```

--------------------------------

### Get Bandwidth call status

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

After an operation that might time out, you can check the status of the operation using the `get` command with the operation's ID.

```bash
band call get <call-id>
```

--------------------------------

### Register a Bandwidth Build Account

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Use this command to create a new Bandwidth Build trial account. Provide required contact information and accept terms of service. For non-interactive use, the `--accept-tos` flag is necessary.

```bash
band account register --phone +19195551234 --email you@example.com --first-name Jane --last-name Doe

# Non-interactive
band account register --phone +19195551234 --email you@example.com --first-name Jane --last-name Doe --accept-tos
```

--------------------------------

### band vcp get

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve VCP details by ID.

```APIDOC
## band vcp get

### Description
Retrieve VCP details.

### Usage
```bash
band vcp get <vcp-id>
```

### Parameters
#### Path Parameters
- **vcp-id** (string) - Required - The ID of the VCP to retrieve.
```

--------------------------------

### band location get

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve location details by ID.

```APIDOC
## band location get

### Description
Retrieve location details.

### Usage
```bash
band location get <location-id>
```

### Parameters
#### Path Parameters
- **location-id** (string) - Required - The ID of the location to retrieve.
```

--------------------------------

### band tfv get

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve TFV campaign details by ID.

```APIDOC
## band tfv get

### Description
Retrieve TFV campaign details.

### Usage
```bash
band tfv get <campaign-id>
```

### Parameters
#### Path Parameters
- **campaign-id** (string) - Required - The ID of the TFV campaign to retrieve.
```

--------------------------------

### Verify Auth and List Resources

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

Before provisioning, verify your authentication status and check for existing sub-accounts and locations. Use `--plain` for machine-readable output.

```bash
band auth status
band subaccount list --plain
band location list --site <site-id> --plain
```

--------------------------------

### Create Site

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Create a new site for your account. A site name is required, and an optional description can be provided.

```bash
band site create [flags]
```

--------------------------------

### band number get

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieves detailed information for a specific phone number.

```APIDOC
## band number get

### Description
Retrieve details for a specific phone number.

### Usage
```bash
band number get <phone-number>
```

### Parameters
#### Path Parameters
- `phone-number` (string) - Required - Phone number in E.164 format (e.g., `+19195551234`)
```

--------------------------------

### Get Application

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieves detailed information for a specific application using its application ID.

```APIDOC
## `band app get`

### Description
Retrieve details for a specific application.

### Usage
```bash
band app get <app-id>
```

### Arguments
- `app-id` — Application ID (required)
```

--------------------------------

### Get Voice API Client

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Retrieves the Voice API client. This can be substituted in tests.

```go
// Get Voice API client
var VoiceClient ClientFunc = voiceClient  // Can be substituted in tests
```

--------------------------------

### Provision Voice from Scratch (Legacy)

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

Commands for provisioning voice services using the legacy method. This is a fallback if Universal Platform provisioning fails.

```bash
band auth status                                                                        # 1. verify auth
band subaccount create --name "Agent Site" --if-not-exists --plain                      # 2. sub-account
band location create --site <site-id> --name "Agent Location" --if-not-exists --plain   # 3. location
band app create --name "Agent Voice" --type voice --callback-url <url> --if-not-exists --plain  # 4. app
band number list --plain                                                                # 5. check numbers
# if no numbers:
band number search --area-code 919 --quantity 1 --plain
band number order <number> --subaccount <subaccount-id> --wait                                                       # 6. order number
```

--------------------------------

### Get Short Code Details

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve specific details for a given short code by its ID.

```bash
band shortcode get <shortcode-id>
```

--------------------------------

### Create Legacy Bandwidth Resources

Source: https://github.com/bandwidth/cli/blob/main/README.md

Use these commands to create a sub-account, location, voice application, search for a phone number, and order it. Ensure you replace placeholders like '<subaccount-id>' and provide a valid callback URL. The `--wait` flag ensures the number order completes before proceeding.

```sh
band subaccount create --name "My Subaccount"
band location create --subaccount <subaccount-id> --name "My Location"
band app create --name "My Voice App" --type voice --callback-url https://your-server.example.com/callbacks
band number search --area-code 919 --quantity 1
band number order +19195551234 --subaccount <subaccount-id> --wait
```

--------------------------------

### band message get

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve details for a specific message using its unique message ID.

```APIDOC
## band message get

### Description
Retrieve details for a specific message.

### Method
GET (implied by get operation)

### Endpoint
/v1/sms/{message-id} (implied by context)

### Parameters
#### Path Parameters
- **message-id** (string) - Required - The unique identifier of the message to retrieve.

#### Query Parameters
None

### Request Example
```bash
band message get msg-12345abcde
```

### Response
#### Success Response (200)
- A message object containing detailed information about the specified message, including `messageId`, `to`, `from`, `status`, `createdAt`, `direction`, `segments`, and `errorCode` (if applicable).

#### Response Example
```json
{
  "messageId": "msg-12345abcde",
  "to": "+15551234567",
  "from": "+15559876543",
  "status": "delivered",
  "createdAt": "2023-10-27T10:00:00Z",
  "direction": "outbound",
  "segments": 1,
  "errorCode": null
}
```
```

--------------------------------

### Get Messaging API Client

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Retrieves the Messaging API client. An account ID override can be specified.

```go
// Get Messaging API client
func MessagingClient(accountIDOverride string) (*api.Client, string, error)
```

--------------------------------

### Register for Trial Account with TOS Acceptance

Source: https://github.com/bandwidth/cli/blob/main/README.md

Registers a new Bandwidth Build trial account and automatically accepts the terms of service via a flag. Useful for scripted registrations.

```sh
band account register --phone +19195551234 --email you@example.com --first-name Jane --last-name Doe --accept-tos
```

--------------------------------

### Clone, Build, Test, and Lint Bandwidth CLI

Source: https://github.com/bandwidth/cli/blob/main/README.md

This snippet shows the basic commands to clone the Bandwidth CLI repository, build the executable, run tests, and perform linting.

```sh
git clone https://github.com/Bandwidth/cli.git
cd cli
make build   # compile → ./band
make test    # run tests
make lint    # run golangci-lint
```

--------------------------------

### Get Dashboard API Client

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Obtains the Dashboard API client. An account ID override can be provided.

```go
// Get Dashboard API client
func DashboardClient(accountIDOverride string) (*api.Client, string, error)
```

--------------------------------

### Generic Authenticated Client Initialization

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/command-structure.md

Initialize a generic authenticated client using cmdutil.BuildClient. This requires specifying the base URL and an optional account ID override.

```go
// Generic authenticated client
client, acctID, err := cmdutil.BuildClient(baseURL, accountIDOverride)
```

--------------------------------

### Upload Media for MMS

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

Upload an image file to get a media URL, which can then be used when sending an MMS message.

```bash
MEDIA_URL=$(band message media upload image.png)
```

--------------------------------

### band call get

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieves detailed information for a specific voice call using its unique Call ID.

```APIDOC
## band call get

### Description
Retrieves detailed information for a specific voice call using its unique Call ID.

### Method
CLI Command

### Endpoint
N/A (CLI Command)

### Parameters
#### Arguments
- `call-id` (STRING) - Required - Call ID

### Request Example
```bash
band call get <some-call-id>
```

### Response
#### Success Response
- **Details**: Returns detailed information about the specified call.

#### Response Example
(CLI command output will show call details.)
```

--------------------------------

### List All 10DLC Campaigns

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

Retrieves a list of all 10DLC campaigns associated with your account. Useful for understanding your current campaign setup.

```bash
band tendlc campaigns --plain
# → [{ "campaignId": "CA3XKE1", "status": "SUCCESS", "brandId": "B1DER2J", ... }, ...]
```

--------------------------------

### List Voice Applications

Source: https://github.com/bandwidth/cli/blob/main/README.md

Lists the voice applications associated with the current account. Useful for verifying setup after account registration.

```sh
band app list
```

--------------------------------

### Bandwidth CLI Package Structure

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/README.md

Illustrates the directory layout of the Bandwidth CLI project, showing the organization of commands, internal utilities, and API clients.

```go
package main

import (
	"fmt"
	"os"

	"github.com/spf13/cobra"
	"github.com/zalando/go-keyring"
	"github.com/olekukonko/tablewriter"
	"golang.org/x/term"
)

var rootCmd = &cobra.Command{
	Use:   "band",
	Short: "Bandwidth CLI",
	Long:  `Command-line interface for the Bandwidth Communications Platform APIs`,
}

func init() {
	// Initialize subcommands here
	rootCmd.AddCommand(authCmd)
	rootCmd.AddCommand(callCmd)
	rootCmd.AddCommand(messageCmd)
	// ... other domains
}

func main() {
	if err := rootCmd.Execute(); err != nil {
		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
		os.Exit(1)
	}
}

// Placeholder for domain commands
var authCmd = &cobra.Command{Use: "auth"}
var callCmd = &cobra.Command{Use: "call"}
var messageCmd = &cobra.Command{Use: "message"}
```

--------------------------------

### Build a Command with Internal Packages

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Demonstrates how to combine internal packages like `api`, `cmdutil`, and `output` to construct a functional CLI command. This snippet shows fetching data using a client and account ID, handling API calls, and formatting the output.

```go
package mycmd

import (
    "fmt"
    "github.com/Bandwidth/cli/internal/api"
    "github.com/Bandwidth/cli/internal/cmdutil"
    "github.com/Bandwidth/cli/internal/output"
    "github.com/spf13/cobra"
)

var myCmd = &cobra.Command{
    Use:   "mycommand",
    Short: "Do something",
    RunE: func(cmd *cobra.Command, args []string) error {
        // Get client and account ID
        client, accountID, err := cmdutil.VoiceClient(cmdutil.AccountIDFlag(cmd))
        if err != nil {
            return err
        }

        // Call API
        var result interface{}
        if err := client.Get(fmt.Sprintf("/accounts/%s/calls", accountID), &result); err != nil {
            return fmt.Errorf("listing calls: %w", err)
        }

        // Output result
        format, plain := cmdutil.OutputFlags(cmd)
        return output.StdoutAuto(format, plain, result)
    },
}
```

--------------------------------

### Generate BXML to Record a Call

Source: https://github.com/bandwidth/cli/blob/main/README.md

Generates BXML to start recording the call, specifying a URL for completion and a maximum duration.

```sh
band bxml record --url https://example.com/done --max-duration 60
```

--------------------------------

### List available applications

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

Lists all applications configured on the account. Use --plain for machine-readable output.

```bash
band app list --plain                   # → [{"ApplicationId":"abc-123", ...}, ...]
```

--------------------------------

### Get location details

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve specific details for a given location by providing its ID. Ensure you have the correct location ID before execution.

```bash
band location get <location-id>
```

--------------------------------

### Get Valid Bearer Token

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Retrieves a valid Bearer token, which is cached and auto-refreshed. The token is automatically refreshed upon expiration.

```Go
func (tm *TokenManager) GetToken() (string, error)
```

--------------------------------

### Get CLI Version for Bug Reports

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

Retrieve the current Bandwidth CLI version, which is useful information to include when reporting bugs.

```bash
band version
```

--------------------------------

### Create a Bandwidth Application

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Create a new voice or messaging application. Specify the application name, type, and callback URL. The `--if-not-exists` flag allows for idempotent creation.

```bash
# Create a voice application
band app create --name "My Voice App" --type voice --callback-url https://example.com/voice

# Create a messaging application
band app create --name "My SMS App" --type messaging --callback-url https://example.com/sms

# Idempotent create (skip if already exists)
band app create --name "My Voice App" --type voice --callback-url https://example.com/voice --if-not-exists
```

--------------------------------

### Register Account

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Creates a new Bandwidth Build trial account. Requires phone, email, first name, and last name. The Terms of Service must be accepted, either interactively or via the --accept-tos flag.

```APIDOC
## `band account register`

### Description
Create a new Bandwidth Build trial account.

### Usage
```bash
band account register [flags]
```

### Parameters
#### Flags
- `--phone STRING` — Phone number in E.164 format (required)
- `--email STRING` — Email address (required)
- `--first-name STRING` — First name (required)
- `--last-name STRING` — Last name (required)
- `--accept-tos` — Accept Terms of Service automatically (required for non-interactive use)

### Behavior
- Prompts to accept the Bandwidth Build Terms of Service unless `--accept-tos` is set
- Creates the account and returns credentials
- After registration, check your email for verification steps and visit the Bandwidth App to generate OAuth2 credentials

### Example
```bash
band account register --phone +19195551234 --email you@example.com --first-name Jane --last-name Doe

# Non-interactive
band account register --phone +19195551234 --email you@example.com --first-name Jane --last-name Doe --accept-tos
```
```

--------------------------------

### Build and Test the CLI

Source: https://github.com/bandwidth/cli/blob/main/CONTRIBUTING.md

Commands to prepare the development environment and verify code quality.

```sh
git clone https://github.com/Bandwidth/cli.git
cd cli
make build   # compile → ./band
make test    # run tests
make lint    # run golangci-lint
```

--------------------------------

### Get VCP details

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve detailed information about a specific VCP by providing its ID. This command helps in understanding the configuration of a particular VCP.

```bash
band vcp get <vcp-id>
```

--------------------------------

### Bandwidth CLI Entry Point

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

The CLI is invoked using the 'band' command followed by global flags, the command name, and command-specific flags. Global flags like account ID and environment can be specified here.

```bash
band [global flags] <command> [command flags]
```

--------------------------------

### Create Basic Auth Client

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Use `NewBasicAuthClient` for HTTP Basic Authentication, typically for legacy endpoints.

```go
func NewBasicAuthClient(baseURL, username, password string) *Client
```

--------------------------------

### Get Site Details

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve detailed information about a specific site using its ID. This command provides comprehensive data for a given site.

```bash
band site get <site-id>
```

--------------------------------

### Get Phone Number Details

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Fetches detailed information for a specific phone number. The phone number must be provided in E.164 format.

```bash
band number get +19195551234
```

--------------------------------

### Get OS and Shell Version for Bug Reports

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

Retrieve your operating system and shell version details, essential for debugging and bug reporting.

```bash
uname -a
```

--------------------------------

### Accessing Positional Arguments

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/command-structure.md

Positional arguments passed to a command are available in the 'args' slice. Access them by their index, for example, args[0] for the first argument.

```go
resourceID := args[0]
```

--------------------------------

### API Error Response Example

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

This JSON structure represents a typical error response from the Bandwidth API, detailing the error type and a descriptive message.

```json
{
  "error": {
    "type": "invalid-phone-number",
    "description": "Phone number format is invalid"
  }
}
```

--------------------------------

### Get TFV campaign details

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve detailed information about a specific TFV campaign by providing its campaign ID. This is useful for inspecting the configuration and status of a campaign.

```bash
band tfv get <campaign-id>
```

--------------------------------

### Detecting Voice Provisioning Path

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

These commands help determine whether to use the Universal Platform or Legacy provisioning path. The responses to `band vcp list --plain` and `band app create --type voice ...` are key indicators.

```bash
band vcp list --plain
```

```bash
band app create --type voice ...
```

--------------------------------

### Create a Messaging Application with Bandwidth CLI

Source: https://github.com/bandwidth/cli/blob/main/README.md

Use this command to create a new messaging application. Ensure you provide a unique name and a valid callback URL for receiving delivery status webhooks.

```sh
band app create --name "My SMS App" --type messaging --callback-url https://your-server.example.com/callbacks
```

--------------------------------

### List All Bandwidth Applications

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference.md

Retrieve a list of all created applications. The output can be formatted as a table for better readability.

```bash
band app list --format table
```

--------------------------------

### Define Create Application Options

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/types.md

Use this struct to define parameters for creating a new voice or messaging application. The Type field must be either "voice" or "messaging".

```go
type CreateOpts struct {
    Name        string // Application name
    Type        string // "voice" or "messaging"
    CallbackURL string // Webhook callback URL
}
```

--------------------------------

### Create a Voice Configuration Package (VCP)

Source: https://github.com/bandwidth/cli/blob/main/README.md

Creates a new VCP with a specified name and associates it with a voice application ID.

```sh
band vcp create --name "My VCP" --app-id <your-app-id>
```

--------------------------------

### Register for a Bandwidth Build Trial Account

Source: https://github.com/bandwidth/cli/blob/main/README.md

Registers a new Bandwidth Build trial account using provided contact and phone number details. Requires accepting terms of service.

```sh
band account register --phone +19195551234 --email you@example.com --first-name Jane --last-name Doe
```

--------------------------------

### Terminal UI Spinner

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Enables the use of animated spinners with custom messages to indicate ongoing processes. Start the spinner before a task and stop it upon completion or failure.

```go
// Create a new spinner with a message
func NewSpinner(message string) *Spinner

// Start the spinner (animated)
func (s *Spinner) Start()

// Stop the spinner (removes it from output)
func (s *Spinner) Stop()
```

--------------------------------

### Check CLI Configuration and Authentication

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

Verify your Bandwidth CLI authentication status and view configured profiles.

```bash
band auth status
```

```bash
band auth profiles
```

--------------------------------

### Create, Get, Hangup, and Redirect Calls

Source: https://github.com/bandwidth/cli/blob/main/README.md

Manage call lifecycles. Use `--answer-url` to specify the webhook for call handling. `<call-id>` is a placeholder for the actual call identifier.

```sh
band call create --from +19195551234 --to +15559876543 --app-id abc-123 --answer-url https://example.com/answer
```

```sh
band call get <call-id>                             # check state
```

```sh
band call hangup <call-id>                          # hang up
```

```sh
band call update <call-id> --redirect-url <url>     # redirect active call
```

--------------------------------

### Universal Platform API Client Initialization

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/command-structure.md

Initialize the client for the Universal Platform v2 using cmdutil.PlatformClient. This function supports an optional account ID override.

```go
// Universal Platform v2
client, acctID, err := cmdutil.PlatformClient(accountIDOverride)
```

--------------------------------

### Log in to Bandwidth CLI

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

Use this command to log in to the Bandwidth CLI by providing your client ID and secret. This is necessary when no client ID is configured in the active profile.

```bash
band auth login --client-id YOUR_ID --client-secret YOUR_SECRET
```

--------------------------------

### Universal Platform Voice Provisioning Flow

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

This outlines the sequence of commands for provisioning voice services using the Universal Platform. It involves creating an application, a VCP, assigning numbers, and activating them.

```bash
auth login
  └─→ app create (voice application with callback URL)
        └─→ vcp create (links to app via --app-id)
              └─→ number search → number order
                    └─→ vcp assign (attach numbers to VCP)
                          └─→ number activate --voice-inbound (required for inbound)
                                └─→ call create (requires --from, --app-id, --answer-url)
```

--------------------------------

### Increase timeout for Bandwidth CLI operation

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

If an operation times out, you can increase the timeout duration using the `--timeout` flag. This example sets a 300-second timeout for creating a call.

```bash
band call create --from +19195551234 --to +15559876543 --app-id abc --answer-url https://example.com/voice --wait --timeout 300s
```

--------------------------------

### CLI Display of API Error

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/errors.md

This example shows how the Bandwidth CLI formats and displays API errors to the user, including the HTTP status code and the JSON error body.

```text
API error 422: {"error": {"type": "invalid-phone-number", ...}}
```

--------------------------------

### Create Token Manager

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/api-reference/internal-packages.md

Initializes a token manager for client credentials flow. Use this to manage OAuth2 tokens.

```Go
func NewTokenManager(clientID, clientSecret, tokenURL string) *TokenManager
```

--------------------------------

### Get Specific Short Code Details

Source: https://github.com/bandwidth/cli/blob/main/AGENTS.md

Retrieves detailed information for a specific short code, including per-carrier activation status. Supports specifying the country for non-US short codes.

```bash
band shortcode get 12345 --plain
band shortcode get 12345 --country CAN --plain    # Canadian short code
```

--------------------------------

### Test a Voice Call with Bandwidth CLI

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/README.md

Initiate a voice call using the CLI. Ensure you replace YOUR_APP_ID with your actual application ID and provide valid 'from' and 'to' phone numbers.

```bash
band call create \
  --from +19195551234 \
  --to +15559876543 \
  --app-id YOUR_APP_ID \
  --answer-url https://example.com/voice \
  --wait
```

--------------------------------

### Bandwidth CLI Output File Structure

Source: https://github.com/bandwidth/cli/blob/main/_autodocs/README.md

Illustrates the typical file and directory structure generated or used by the Bandwidth CLI.

```bash
output/
├── README.md                          # This file
├── api-reference.md                   # Main CLI reference
├── types.md                           # Type definitions
├── configuration.md                   # Configuration guide
├── errors.md                          # Error reference
└── api-reference/
    ├── internal-packages.md           # Internal API reference
    └── command-structure.md           # Command architecture
```