SWI-11010 Update Long + Example for Better Docs (#14)

* call docs

* recording docs

* transcription docs

* app docs

* site docs

* location docs

* vcp docs

* account docs

* auth docs

* bxml docs

* message docs

* number docs

* tnoption docs

* fix auth switch

* gofmt

Author: ckoegel

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 {