Merge branch 'main' into recording-pause-resume

Author: kshahbw

.github/workflows/release.yml

@@ -61,6 +61,27 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  dispatch-docsite:
+    needs: [release]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Mint app token for api-specs
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ secrets.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          owner: Bandwidth
+          repositories: api-specs
+
+      - name: Trigger docsite CLI reference update
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          gh api repos/Bandwidth/api-specs/dispatches \
+            -f event_type=cli-docs-update \
+            -F client_payload[version]="${{ github.ref_name }}"
+
   bump-formula:
     needs: [release]
     runs-on: ubuntu-latest

.goreleaser.yml

@@ -1,5 +1,10 @@
 version: 2
 
+before:
+  hooks:
+    - go run ./internal/tools/docgen -out ./dist-docs
+    - tar -czf cli-docs.tar.gz -C ./dist-docs .
+
 builds:
   - main: ./cmd/band
     binary: band
@@ -25,6 +30,11 @@ archives:
 checksum:
   name_template: "checksums.txt"
 
+release:
+  # Attach docs to the GitHub release
+  extra_files:
+    - glob: ./cli-docs.tar.gz
+
 dockers:
   - image_templates:
       - "ghcr.io/bandwidth/cli:{{ .Version }}-amd64"

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() {