SWI-11010 Update Long + Example for Better Docs

cmd/account/account.go

@@ -6,4 +6,5 @@ import "github.com/spf13/cobra"
 var Cmd = &cobra.Command{
 	Use:   "account",
 	Short: "Manage Bandwidth account registration",
+	Long:  "Register and provision Bandwidth accounts. These commands handle account onboarding and do not require an existing account to be selected.",
 }

cmd/app/app.go

@@ -6,4 +6,5 @@ import "github.com/spf13/cobra"
 var Cmd = &cobra.Command{
 	Use:   "app",
 	Short: "Manage Bandwidth applications",
+	Long:  "Create, inspect, and manage Bandwidth applications. Applications hold the callback configuration that voice and messaging traffic is routed against, and are referenced by ID when sending messages or placing calls.",
 }

cmd/app/create.go

@@ -32,6 +32,7 @@ func init() {
 var createCmd = &cobra.Command{
 	Use:   "create",
 	Short: "Create a new application",
+	Long:  "Creates a new voice or messaging application. The callback URL receives webhook events for traffic routed through the application. Use --if-not-exists to make the command idempotent, returning the existing application instead of erroring when one with the same name already exists.",
 	Example: `  # Create a voice application
   band app create --name "My Voice App" --type voice --callback-url https://example.com/voice
 

cmd/app/delete.go

@@ -14,10 +14,12 @@ func init() {
 }
 
 var deleteCmd = &cobra.Command{
-	Use:   "delete [id]",
-	Short: "Delete an application by ID",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runDelete,
+	Use:     "delete [id]",
+	Short:   "Delete an application by ID",
+	Long:    "Permanently deletes an application by its ID. This cannot be undone.",
+	Example: `  band app delete abc-123`,
+	Args:    cobra.ExactArgs(1),
+	RunE:    runDelete,
 }
 
 func runDelete(cmd *cobra.Command, args []string) error {

cmd/app/get.go

@@ -17,8 +17,11 @@ func init() {
 var getCmd = &cobra.Command{
 	Use:   "get [id]",
 	Short: "Get an application by ID",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runGet,
+	Long:  "Returns the details of a single application by its ID, including its type and callback configuration.",
+	Example: `  band app get abc-123
+  band app get abc-123 --plain`,
+	Args: cobra.ExactArgs(1),
+	RunE: runGet,
 }
 
 func runGet(cmd *cobra.Command, args []string) error {

cmd/app/list.go

@@ -16,7 +16,10 @@ func init() {
 var listCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List all applications",
-	RunE:  runList,
+	Long:  "Lists all applications on the account, both voice and messaging.",
+	Example: `  band app list
+  band app list --plain`,
+	RunE: runList,
 }
 
 func runList(cmd *cobra.Command, args []string) error {

cmd/app/peers.go

@@ -17,8 +17,11 @@ func init() {
 var peersCmd = &cobra.Command{
 	Use:   "peers [app-id]",
 	Short: "List SIP peers (locations) associated with an application",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runPeers,
+	Long:  "Lists the SIP peers (locations) associated with an application. Returns an empty list when no peers are associated.",
+	Example: `  band app peers abc-123
+  band app peers abc-123 --plain`,
+	Args: cobra.ExactArgs(1),
+	RunE: runPeers,
 }
 
 func runPeers(cmd *cobra.Command, args []string) error {

cmd/auth/login.go

@@ -19,6 +19,7 @@ import (
 var Cmd = &cobra.Command{
 	Use:   "auth",
 	Short: "Manage authentication credentials",
+	Long:  "Log in with Bandwidth OAuth2 client credentials, inspect your authentication status, and manage credential profiles and the active account.",
 }
 
 func init() {

cmd/auth/logout.go

@@ -16,9 +16,11 @@ func init() {
 }
 
 var logoutCmd = &cobra.Command{
-	Use:   "logout",
-	Short: "Log out and remove stored credentials",
-	RunE:  runLogout,
+	Use:     "logout",
+	Short:   "Log out and remove stored credentials",
+	Long:    "Logs out by deleting stored secrets from the system keychain and removing the CLI config file. This affects all profiles, not just the active one.",
+	Example: `  band auth logout`,
+	RunE:    runLogout,
 }
 
 func runLogout(cmd *cobra.Command, args []string) error {

cmd/auth/profiles.go

@@ -15,9 +15,11 @@ func init() {
 }
 
 var profilesCmd = &cobra.Command{
-	Use:   "profiles",
-	Short: "List all credential profiles",
-	RunE:  runProfiles,
+	Use:     "profiles",
+	Short:   "List all credential profiles",
+	Long:    "Lists all configured credential profiles, marking the active one. Each profile holds its own client credentials, account, and environment.",
+	Example: `  band auth profiles`,
+	RunE:    runProfiles,
 }
 
 func runProfiles(cmd *cobra.Command, args []string) error {
@@ -70,10 +72,12 @@ func runProfiles(cmd *cobra.Command, args []string) error {
 }
 
 var useCmd = &cobra.Command{
-	Use:   "use <profile>",
-	Short: "Switch to a different credential profile",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runUse,
+	Use:     "use <profile>",
+	Short:   "Switch to a different credential profile",
+	Long:    "Switches the active credential profile. Subsequent commands use the selected profile's credentials, account, and environment.",
+	Example: `  band auth use admin`,
+	Args:    cobra.ExactArgs(1),
+	RunE:    runUse,
 }
 
 func runUse(cmd *cobra.Command, args []string) error {

cmd/auth/status.go

@@ -21,7 +21,10 @@ func init() {
 var statusCmd = &cobra.Command{
 	Use:   "status",
 	Short: "Show current authentication status",
-	RunE:  runStatus,
+	Long:  "Shows the active profile's authentication status, including client ID, active account, environment, and (for Bandwidth Build accounts) capabilities. Use --plain for machine-readable JSON.",
+	Example: `  band auth status
+  band auth status --plain`,
+	RunE: runStatus,
 }
 
 // statusJSON is the structured output shape returned when --plain is set.

cmd/auth/switch.go

@@ -19,9 +19,8 @@ func init() {
 var switchCmd = &cobra.Command{
 	Use:   "switch [account-id]",
 	Short: "Switch the active account",
-	Long: `Switch between accounts accessible to your credentials.
-
-  band auth switch           # interactive selection
+	Long:  `Switch between accounts accessible to your credentials.`,
+	Example: `  band auth switch           # interactive selection
   band auth switch 9901303   # switch directly`,
 	Args: cobra.MaximumNArgs(1),
 	RunE: runSwitch,

cmd/bxml/gather.go

@@ -24,8 +24,11 @@ func init() {
 var gatherCmd = &cobra.Command{
 	Use:   "gather",
 	Short: "Generate a Gather BXML verb",
-	Args:  cobra.NoArgs,
-	RunE:  runGather,
+	Long:  "Generates a Response containing a Gather verb that collects DTMF digits and posts them to --url. Use --prompt to speak a message before gathering and --max-digits to cap input length.",
+	Example: `  band bxml gather --url https://example.com/voice/gather
+  band bxml gather --url https://example.com/voice/gather --prompt "Press 1 for sales." --max-digits 1`,
+	Args: cobra.NoArgs,
+	RunE: runGather,
 }
 
 func runGather(cmd *cobra.Command, args []string) error {

cmd/bxml/raw.go

@@ -13,10 +13,12 @@ func init() {
 }
 
 var rawCmd = &cobra.Command{
-	Use:   "raw <xml-string>",
-	Short: "Validate and pretty-print a BXML string",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runRaw,
+	Use:     "raw <xml-string>",
+	Short:   "Validate and pretty-print a BXML string",
+	Long:    "Validates a BXML string by round-tripping it through an XML parser and prints it back indented. Exits with an error if the input is not well-formed XML.",
+	Example: `  band bxml raw "<Response><Hangup/></Response>"`,
+	Args:    cobra.ExactArgs(1),
+	RunE:    runRaw,
 }
 
 func runRaw(cmd *cobra.Command, args []string) error {

cmd/bxml/record.go

@@ -21,8 +21,11 @@ func init() {
 var recordCmd = &cobra.Command{
 	Use:   "record",
 	Short: "Generate a Record BXML verb",
-	Args:  cobra.NoArgs,
-	RunE:  runRecord,
+	Long:  "Generates a Response containing a Record verb. Use --url to receive the recording-complete event and --max-duration to limit the recording length in seconds.",
+	Example: `  band bxml record
+  band bxml record --url https://example.com/voice/recorded --max-duration 30`,
+	Args: cobra.NoArgs,
+	RunE: runRecord,
 }
 
 func runRecord(cmd *cobra.Command, args []string) error {

cmd/bxml/speak.go

@@ -18,6 +18,7 @@ func init() {
 var speakCmd = &cobra.Command{
 	Use:   "speak <text>",
 	Short: "Generate a SpeakSentence BXML verb",
+	Long:  "Generates a Response containing a SpeakSentence verb for the given text. Use --voice to select a specific Bandwidth voice.",
 	Example: `  band bxml speak "Hello, welcome to Bandwidth."
   band bxml speak --voice julie "Press 1 for sales."
   band bxml speak "Goodbye." > hangup.xml`,

cmd/bxml/transfer.go

@@ -17,8 +17,11 @@ func init() {
 var transferCmd = &cobra.Command{
 	Use:   "transfer <phone-number>",
 	Short: "Generate a Transfer BXML verb",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runTransfer,
+	Long:  "Generates a Response containing a Transfer verb to the given phone number. Use --caller-id to set the caller ID presented on the transferred leg.",
+	Example: `  band bxml transfer +19195551234
+  band bxml transfer +19195551234 --caller-id +19198675309`,
+	Args: cobra.ExactArgs(1),
+	RunE: runTransfer,
 }
 
 func runTransfer(cmd *cobra.Command, args []string) error {

cmd/call/call.go

@@ -6,4 +6,5 @@ import "github.com/spf13/cobra"
 var Cmd = &cobra.Command{
 	Use:   "call",
 	Short: "Manage Bandwidth voice calls",
+	Long:  "Create, inspect, and control voice calls. Place outbound calls, redirect calls to new BXML, hang up active calls, and look up call state.",
 }

cmd/call/get.go

@@ -17,8 +17,11 @@ func init() {
 var getCmd = &cobra.Command{
 	Use:   "get [callId]",
 	Short: "Get the state of a call",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runGet,
+	Long:  "Returns the current state and details of a single call, including its direction, endpoints, and timing. Use the callId returned when the call was created.",
+	Example: `  band call get c-123-abc
+  band call get c-123-abc --plain`,
+	Args: cobra.ExactArgs(1),
+	RunE: runGet,
 }
 
 func runGet(cmd *cobra.Command, args []string) error {

cmd/call/hangup.go

@@ -15,10 +15,12 @@ func init() {
 }
 
 var hangupCmd = &cobra.Command{
-	Use:   "hangup [callId]",
-	Short: "Hang up an active call",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runHangup,
+	Use:     "hangup [callId]",
+	Short:   "Hang up an active call",
+	Long:    "Ends an active call by transitioning it to the completed state. Has no effect on calls that have already disconnected.",
+	Example: `  band call hangup c-123-abc`,
+	Args:    cobra.ExactArgs(1),
+	RunE:    runHangup,
 }
 
 func runHangup(cmd *cobra.Command, args []string) error {

cmd/call/list.go

@@ -16,7 +16,10 @@ func init() {
 var listCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List active and recent calls",
-	RunE:  runList,
+	Long:  "Lists calls for the account, including active calls and recently completed ones. Bandwidth retains call records for a limited window, so older calls may not appear.",
+	Example: `  band call list
+  band call list --plain`,
+	RunE: runList,
 }
 
 func runList(cmd *cobra.Command, args []string) error {

cmd/call/update.go

@@ -19,10 +19,12 @@ func init() {
 }
 
 var updateCmd = &cobra.Command{
-	Use:   "update [callId]",
-	Short: "Redirect an active call to a new URL",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runUpdate,
+	Use:     "update [callId]",
+	Short:   "Redirect an active call to a new URL",
+	Long:    "Redirects an active call to fetch new BXML from the given URL. Bandwidth POSTs to the redirect URL and replaces the call's current instructions with the response.",
+	Example: `  band call update c-123-abc --redirect-url https://example.com/voice/next`,
+	Args:    cobra.ExactArgs(1),
+	RunE:    runUpdate,
 }
 
 func runUpdate(cmd *cobra.Command, args []string) error {

cmd/location/create.go

@@ -28,7 +28,12 @@ func init() {
 var createCmd = &cobra.Command{
 	Use:   "create",
 	Short: "Create a new location (SIP peer) under a sub-account",
-	RunE:  runCreate,
+	Long:  "Creates a new location (SIP peer) within the given sub-account. Use --if-not-exists to make the command idempotent, returning the existing location instead of erroring when one with the same name already exists.",
+	Example: `  band location create --site 12345 --name "Primary SIP"
+
+  # Idempotent — safe to re-run
+  band location create --site 12345 --name "Primary SIP" --if-not-exists`,
+	RunE: runCreate,
 }
 
 func runCreate(cmd *cobra.Command, args []string) error {

cmd/location/list.go

@@ -20,7 +20,10 @@ func init() {
 var listCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List all locations (SIP peers) under a sub-account",
-	RunE:  runList,
+	Long:  "Lists all locations (SIP peers) within the given sub-account.",
+	Example: `  band location list --site 12345
+  band location list --site 12345 --plain`,
+	RunE: runList,
 }
 
 func runList(cmd *cobra.Command, args []string) error {

cmd/location/location.go

@@ -6,4 +6,5 @@ import "github.com/spf13/cobra"
 var Cmd = &cobra.Command{
 	Use:   "location",
 	Short: "Manage locations (SIP peers) under sub-accounts",
+	Long:  "Create and list locations (SIP peers) within a sub-account. Locations define the SIP endpoints that route voice traffic for the numbers assigned to them.",
 }

cmd/message/get.go

@@ -18,8 +18,10 @@ var getCmd = &cobra.Command{
 	Use:   "get [messageId]",
 	Short: "Get message metadata by ID",
 	Long:  "Retrieves metadata for a specific message. Note: Bandwidth does not store message content — only metadata (timestamps, direction, segment count) is returned.",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runGet,
+	Example: `  band message get 1234567890abcdefghij
+  band message get 1234567890abcdefghij --plain`,
+	Args: cobra.ExactArgs(1),
+	RunE: runGet,
 }
 
 func runGet(cmd *cobra.Command, args []string) error {

cmd/message/media/delete.go

@@ -14,10 +14,12 @@ func init() {
 }
 
 var deleteCmd = &cobra.Command{
-	Use:   "delete <mediaId>",
-	Short: "Delete a media file",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runDelete,
+	Use:     "delete <mediaId>",
+	Short:   "Delete a media file",
+	Long:    "Permanently deletes a media file by its ID. Any MMS that still references its URL will no longer be able to fetch it.",
+	Example: `  band message media delete my-campaign-image.jpg`,
+	Args:    cobra.ExactArgs(1),
+	RunE:    runDelete,
 }
 
 func runDelete(cmd *cobra.Command, args []string) error {

cmd/message/media/get.go

@@ -18,10 +18,12 @@ func init() {
 }
 
 var getCmd = &cobra.Command{
-	Use:   "get <mediaId>",
-	Short: "Download a media file",
-	Args:  cobra.ExactArgs(1),
-	RunE:  runGet,
+	Use:     "get <mediaId>",
+	Short:   "Download a media file",
+	Long:    "Downloads a media file by its ID and writes it to the given file path.",
+	Example: `  band message media get my-campaign-image.jpg --output image.jpg`,
+	Args:    cobra.ExactArgs(1),
+	RunE:    runGet,
 }
 
 func runGet(cmd *cobra.Command, args []string) error {

cmd/message/media/list.go

@@ -16,7 +16,10 @@ func init() {
 var listCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List uploaded media files",
-	RunE:  runList,
+	Long:  "Lists the media files uploaded to the account's media store.",
+	Example: `  band message media list
+  band message media list --plain`,
+	RunE: runList,
 }
 
 func runList(cmd *cobra.Command, args []string) error {

cmd/message/media/media.go

@@ -6,4 +6,5 @@ import "github.com/spf13/cobra"
 var Cmd = &cobra.Command{
 	Use:   "media",
 	Short: "Manage MMS media files",
+	Long:  "Upload, list, download, and delete the media files served for MMS. Uploaded media is hosted by Bandwidth and referenced by URL when sending an MMS with 'message send --media'.",
 }

cmd/message/message.go

@@ -10,6 +10,7 @@ import (
 var Cmd = &cobra.Command{
 	Use:   "message",
 	Short: "Send and manage SMS/MMS messages",
+	Long:  "Send SMS and MMS messages, look up message metadata, and manage the media files used in MMS. Delivery is asynchronous — status arrives via webhook callbacks on your messaging application.",
 }
 
 func init() {