feat(api): thread context.Context through the client; cancel cleanly on SIGINT

AGENTS.md

@@ -1173,17 +1173,15 @@ still-pending.
 carries `bandwidthId` somewhere in valid JSON — that ID is the one thing that
 cannot be recovered any other way if the command exits without printing it.
 
-**This guarantee covers every path the command itself takes — it does not
-cover an interrupt.** `cmd/root.go`'s `Execute()` runs with no context, and
-the CLI does not install a `SIGINT` handler anywhere (no `signal.Notify` /
-`signal.NotifyContext` in the codebase), so the cancellation branch in
-`awaitTerminal` that exists specifically to emit this receipt can never
-actually fire from a real Ctrl-C. Press Ctrl-C during `--wait` after the 202
-has landed and the process dies immediately with no `bandwidthId` on stdout.
-If that happens, recover with `band tendlc brand list --customer-profile-id-contains
-<id>` to find the brand that was accepted. This applies CLI-wide, not just to
-`tendlc` — it is a pre-existing, repo-wide gap, tracked separately from this
-PR.
+**The guarantee covers a single Ctrl-C too.** `cmd/root.go`'s `Execute()`
+runs the command tree under `signal.NotifyContext`, so the first
+`SIGINT`/`SIGTERM` cancels `cmd.Context()` rather than killing the process:
+the in-flight request aborts, the cancellation branch in `awaitTerminal`
+fires, and the receipt (with `bandwidthId`) lands on stdout before the
+command exits. A **second** Ctrl-C is not trapped — it hard-kills the
+process the Go-default way, with nothing further on stdout. If a receipt was
+lost that way, recover with `band tendlc brand list
+--customer-profile-id-contains <id>` to find the brand that was accepted.
 
 Without `--wait`, or on a timeout/transport failure with `--wait`, that's the
 literal synthetic receipt: `{"bandwidthId": "...", "status": "accepted",
@@ -1794,9 +1792,10 @@ carries `bandwidthId` somewhere in valid JSON — the one thing that cannot be
 recovered any other way if the command exits without printing it. This
 covers `create`, `sync`, and `update` alike, all of which share the same
 `{bandwidthId, campaignId (if present), status: "accepted", resume}`
-receipt shape. As with `brand create`, this guarantee does not extend past a
-`SIGINT` — see the equivalent note under [10DLC Brands](#create) for why and
-how to recover (`band tendlc campaign list --brand-id-contains <id>`).
+receipt shape. As with `brand create`, a single `SIGINT` is covered (the
+receipt is emitted before exit); only a second Ctrl-C hard-kills the process
+— see the equivalent note under [10DLC Brands](#create), and recover with
+`band tendlc campaign list --brand-id-contains <id>`.
 
 ### `deactivate`'s honest receipt
 

cmd/account/register.go

@@ -94,7 +94,7 @@ func runRegister(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Post("/registration", reqBody, &result); err != nil {
+	if err := client.Post(cmd.Context(), "/registration", reqBody, &result); err != nil {
 		return fmt.Errorf("registering account: %w", err)
 	}
 

cmd/app/assign.go

@@ -65,7 +65,7 @@ func runAssign(cmd *cobra.Command, args []string) error {
 		acctID, url.PathEscape(assignSite), url.PathEscape(assignLocation))
 
 	var result interface{}
-	if err := client.Put(path, body, &result); err != nil {
+	if err := client.Put(cmd.Context(), path, body, &result); err != nil {
 		return fmt.Errorf("assigning application to location: %w", err)
 	}
 

cmd/app/create.go

@@ -95,7 +95,7 @@ func runCreate(cmd *cobra.Command, args []string) error {
 
 	if createIfNotExists {
 		var listResult interface{}
-		if err := client.Get(fmt.Sprintf("/accounts/%s/applications", acctID), &listResult); err != nil {
+		if err := client.Get(cmd.Context(), fmt.Sprintf("/accounts/%s/applications", acctID), &listResult); err != nil {
 			return fmt.Errorf("listing applications: %w", err)
 		}
 		if existing := output.FindByName(listResult, "AppName", createName); existing != nil {
@@ -106,7 +106,7 @@ func runCreate(cmd *cobra.Command, args []string) error {
 	bodyData := BuildCreateBody(opts)
 
 	var result interface{}
-	if err := client.Post(fmt.Sprintf("/accounts/%s/applications", acctID), api.XMLBody{RootElement: "Application", Data: bodyData}, &result); err != nil {
+	if err := client.Post(cmd.Context(), fmt.Sprintf("/accounts/%s/applications", acctID), api.XMLBody{RootElement: "Application", Data: bodyData}, &result); err != nil {
 		if strings.Contains(err.Error(), "HTTP voice feature is required") {
 			return fmt.Errorf("creating voice application: this account requires the HTTP Voice feature to be enabled.\n" +
 				"Contact Bandwidth support to enable it, or check if your account is on the Universal Platform.\n" +

cmd/app/delete.go

@@ -31,7 +31,7 @@ func runDelete(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	if err := client.Delete(fmt.Sprintf("/accounts/%s/applications/%s", acctID, url.PathEscape(args[0])), nil); err != nil {
+	if err := client.Delete(cmd.Context(), fmt.Sprintf("/accounts/%s/applications/%s", acctID, url.PathEscape(args[0])), nil); err != nil {
 		return fmt.Errorf("deleting application: %w", err)
 	}
 

cmd/app/get.go

@@ -34,7 +34,7 @@ func runGet(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Get(fmt.Sprintf("/accounts/%s/applications/%s", acctID, url.PathEscape(args[0])), &result); err != nil {
+	if err := client.Get(cmd.Context(), fmt.Sprintf("/accounts/%s/applications/%s", acctID, url.PathEscape(args[0])), &result); err != nil {
 		return fmt.Errorf("getting application: %w", err)
 	}
 

cmd/app/list.go

@@ -29,7 +29,7 @@ func runList(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Get(fmt.Sprintf("/accounts/%s/applications", acctID), &result); err != nil {
+	if err := client.Get(cmd.Context(), fmt.Sprintf("/accounts/%s/applications", acctID), &result); err != nil {
 		return fmt.Errorf("listing applications: %w", err)
 	}
 

cmd/app/peers.go

@@ -32,7 +32,7 @@ func runPeers(cmd *cobra.Command, args []string) error {
 
 	var result interface{}
 	path := fmt.Sprintf("/accounts/%s/applications/%s/associatedsippeers", acctID, url.PathEscape(args[0]))
-	if err := client.Get(path, &result); err != nil {
+	if err := client.Get(cmd.Context(), path, &result); err != nil {
 		return fmt.Errorf("getting application peers: %w", err)
 	}
 

cmd/app/update.go

@@ -50,7 +50,7 @@ func runUpdate(cmd *cobra.Command, args []string) error {
 
 	// First, get the existing app to determine its type
 	var existing interface{}
-	if err := client.Get(fmt.Sprintf("/accounts/%s/applications/%s", acctID, url.PathEscape(appID)), &existing); err != nil {
+	if err := client.Get(cmd.Context(), fmt.Sprintf("/accounts/%s/applications/%s", acctID, url.PathEscape(appID)), &existing); err != nil {
 		return fmt.Errorf("getting application: %w", err)
 	}
 
@@ -80,7 +80,7 @@ func runUpdate(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Put(fmt.Sprintf("/accounts/%s/applications/%s", acctID, url.PathEscape(appID)), body, &result); err != nil {
+	if err := client.Put(cmd.Context(), fmt.Sprintf("/accounts/%s/applications/%s", acctID, url.PathEscape(appID)), body, &result); err != nil {
 		return fmt.Errorf("updating application: %w", err)
 	}
 

cmd/call/create.go

@@ -87,7 +87,7 @@ func runCreate(cmd *cobra.Command, args []string) error {
 	})
 
 	var result interface{}
-	if err := client.Post(fmt.Sprintf("/accounts/%s/calls", acctID), reqBody, &result); err != nil {
+	if err := client.Post(cmd.Context(), fmt.Sprintf("/accounts/%s/calls", acctID), reqBody, &result); err != nil {
 		return fmt.Errorf("creating call: %w", err)
 	}
 
@@ -103,11 +103,12 @@ func runCreate(cmd *cobra.Command, args []string) error {
 	}
 
 	final, err := cmdutil.Poll(cmdutil.PollConfig{
+		Context:  cmd.Context(),
 		Interval: 2 * time.Second,
 		Timeout:  createTimeout,
 		Check: func() (bool, interface{}, error) {
 			var callState interface{}
-			if err := client.Get(fmt.Sprintf("/accounts/%s/calls/%s", acctID, url.PathEscape(callID)), &callState); err != nil {
+			if err := client.Get(cmd.Context(), fmt.Sprintf("/accounts/%s/calls/%s", acctID, url.PathEscape(callID)), &callState); err != nil {
 				// The Voice API is eventually consistent — a 404 right after
 				// creation means the call record hasn't propagated yet. Retry.
 				var apiErr *api.APIError

cmd/call/get.go

@@ -34,7 +34,7 @@ func runGet(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Get(fmt.Sprintf("/accounts/%s/calls/%s", acctID, url.PathEscape(args[0])), &result); err != nil {
+	if err := client.Get(cmd.Context(), fmt.Sprintf("/accounts/%s/calls/%s", acctID, url.PathEscape(args[0])), &result); err != nil {
 		return fmt.Errorf("getting call: %w", err)
 	}
 

cmd/call/hangup.go

@@ -37,7 +37,7 @@ func runHangup(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Post(fmt.Sprintf("/accounts/%s/calls/%s", acctID, url.PathEscape(args[0])), reqBody, &result); err != nil {
+	if err := client.Post(cmd.Context(), fmt.Sprintf("/accounts/%s/calls/%s", acctID, url.PathEscape(args[0])), reqBody, &result); err != nil {
 		return fmt.Errorf("hanging up call: %w", err)
 	}
 

cmd/call/list.go

@@ -29,7 +29,7 @@ func runList(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Get(fmt.Sprintf("/accounts/%s/calls", acctID), &result); err != nil {
+	if err := client.Get(cmd.Context(), fmt.Sprintf("/accounts/%s/calls", acctID), &result); err != nil {
 		return fmt.Errorf("listing calls: %w", err)
 	}
 

cmd/call/update.go

@@ -42,7 +42,7 @@ func runUpdate(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Post(fmt.Sprintf("/accounts/%s/calls/%s", acctID, url.PathEscape(args[0])), reqBody, &result); err != nil {
+	if err := client.Post(cmd.Context(), fmt.Sprintf("/accounts/%s/calls/%s", acctID, url.PathEscape(args[0])), reqBody, &result); err != nil {
 		return fmt.Errorf("updating call: %w", err)
 	}
 

cmd/customerprofile/create.go

@@ -51,7 +51,7 @@ retry — list profiles and reconcile against what you submitted first.`,
 		if err != nil {
 			return err
 		}
-		env, err := svc.Create(cpsvc.BuildCreateRequest(createOpts))
+		env, err := svc.Create(cmd.Context(), cpsvc.BuildCreateRequest(createOpts))
 		if err != nil {
 			return roleGateError(err)
 		}

cmd/customerprofile/delete.go

@@ -42,7 +42,7 @@ attached.`,
 		if err != nil {
 			return err
 		}
-		if err := svc.Delete(args[0]); err != nil {
+		if err := svc.Delete(cmd.Context(), args[0]); err != nil {
 			return roleGateError(err)
 		}
 		format, plain := cmdutil.OutputFlags(cmd)
@@ -73,7 +73,7 @@ No --confirm needed: restoring is not destructive.`,
 		if err != nil {
 			return err
 		}
-		env, err := svc.Get(args[0])
+		env, err := svc.Get(cmd.Context(), args[0])
 		if err != nil {
 			return roleGateError(err)
 		}
@@ -85,7 +85,7 @@ No --confirm needed: restoring is not destructive.`,
 		if err != nil {
 			return err
 		}
-		restored, err := svc.Update(args[0], body)
+		restored, err := svc.Update(cmd.Context(), args[0], body)
 		if err != nil {
 			return roleGateError(conflictHint(err))
 		}

cmd/customerprofile/get.go

@@ -20,7 +20,7 @@ var getCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
-		env, err := svc.Get(args[0])
+		env, err := svc.Get(cmd.Context(), args[0])
 		if err != nil {
 			return roleGateError(err)
 		}

cmd/customerprofile/history.go

@@ -53,7 +53,7 @@ CREATED, UPDATED, and DELETED.`,
 		format, plain := cmdutil.OutputFlags(cmd)
 
 		if !historyAll {
-			env, err := svc.History(args[0], historyLimit, historyOffset)
+			env, err := svc.History(cmd.Context(), args[0], historyLimit, historyOffset)
 			if err != nil {
 				return roleGateError(err)
 			}
@@ -67,7 +67,7 @@ CREATED, UPDATED, and DELETED.`,
 
 		var all []any
 		err = api.ForEachPage(func(limit, offset int) (*api.Envelope, error) {
-			return svc.History(args[0], limit, offset)
+			return svc.History(cmd.Context(), args[0], limit, offset)
 		}, historyLimit, func(batch []any) error {
 			all = append(all, batch...)
 			return nil
@@ -101,7 +101,7 @@ count: list always returns an array, get always returns an object.`,
 		if err != nil {
 			return err
 		}
-		env, err := svc.HistoryVersion(args[0], args[1])
+		env, err := svc.HistoryVersion(cmd.Context(), args[0], args[1])
 		if err != nil {
 			return roleGateError(err)
 		}

cmd/customerprofile/list.go

@@ -51,7 +51,7 @@ var listCmd = &cobra.Command{
 		format, plain := cmdutil.OutputFlags(cmd)
 
 		if !listAll {
-			env, err := svc.List(listLimit, listOffset, filters)
+			env, err := svc.List(cmd.Context(), listLimit, listOffset, filters)
 			if err != nil {
 				return roleGateError(err)
 			}
@@ -65,7 +65,7 @@ var listCmd = &cobra.Command{
 
 		var all []any
 		err = api.ForEachPage(func(limit, offset int) (*api.Envelope, error) {
-			return svc.List(limit, offset, filters)
+			return svc.List(cmd.Context(), limit, offset, filters)
 		}, listLimit, func(batch []any) error {
 			all = append(all, batch...)
 			return nil

cmd/customerprofile/update.go

@@ -61,7 +61,7 @@ is rejected by the API's version check — the command exits 4 and you can retry
 			return err
 		}
 
-		env, err := svc.Get(args[0])
+		env, err := svc.Get(cmd.Context(), args[0])
 		if err != nil {
 			return roleGateError(err)
 		}
@@ -75,7 +75,7 @@ is rejected by the API's version check — the command exits 4 and you can retry
 			return err
 		}
 
-		updated, err := svc.Update(args[0], body)
+		updated, err := svc.Update(cmd.Context(), args[0], body)
 		if err != nil {
 			return roleGateError(conflictHint(err))
 		}

cmd/location/create.go

@@ -47,7 +47,7 @@ func runCreate(cmd *cobra.Command, args []string) error {
 	if createIfNotExists {
 		var listResult interface{}
 		listPath := fmt.Sprintf("/accounts/%s/sites/%s/sippeers", acctID, createSiteID)
-		if err := client.Get(listPath, &listResult); err != nil {
+		if err := client.Get(cmd.Context(), listPath, &listResult); err != nil {
 			return fmt.Errorf("listing locations: %w", err)
 		}
 		if existing := output.FindByName(listResult, "PeerName", createName); existing != nil {
@@ -61,7 +61,7 @@ func runCreate(cmd *cobra.Command, args []string) error {
 
 	var result interface{}
 	path := fmt.Sprintf("/accounts/%s/sites/%s/sippeers", acctID, createSiteID)
-	if err := client.Post(path, api.XMLBody{RootElement: "SipPeer", Data: bodyData}, &result); err != nil {
+	if err := client.Post(cmd.Context(), path, api.XMLBody{RootElement: "SipPeer", Data: bodyData}, &result); err != nil {
 		return fmt.Errorf("creating location: %w", err)
 	}
 

cmd/location/list.go

@@ -34,7 +34,7 @@ func runList(cmd *cobra.Command, args []string) error {
 
 	var result interface{}
 	path := fmt.Sprintf("/accounts/%s/sites/%s/sippeers", acctID, listSiteID)
-	if err := client.Get(path, &result); err != nil {
+	if err := client.Get(cmd.Context(), path, &result); err != nil {
 		return fmt.Errorf("listing locations: %w", err)
 	}
 

cmd/message/get.go

@@ -34,7 +34,7 @@ func runGet(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Get(fmt.Sprintf("/users/%s/messages?messageId=%s", acctID, url.QueryEscape(args[0])), &result); err != nil {
+	if err := client.Get(cmd.Context(), fmt.Sprintf("/users/%s/messages?messageId=%s", acctID, url.QueryEscape(args[0])), &result); err != nil {
 		return fmt.Errorf("getting message: %w", err)
 	}
 

cmd/message/list.go

@@ -67,7 +67,7 @@ func runList(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Get(path, &result); err != nil {
+	if err := client.Get(cmd.Context(), path, &result); err != nil {
 		return fmt.Errorf("listing messages: %w", err)
 	}
 

cmd/message/media/delete.go

@@ -31,7 +31,7 @@ func runDelete(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	if err := client.Delete(fmt.Sprintf("/users/%s/media/%s", acctID, args[0]), nil); err != nil {
+	if err := client.Delete(cmd.Context(), fmt.Sprintf("/users/%s/media/%s", acctID, args[0]), nil); err != nil {
 		return fmt.Errorf("deleting media: %w", err)
 	}
 

cmd/message/media/get.go

@@ -35,7 +35,7 @@ func runGet(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	data, err := client.GetRaw(fmt.Sprintf("/users/%s/media/%s", acctID, args[0]))
+	data, err := client.GetRaw(cmd.Context(), fmt.Sprintf("/users/%s/media/%s", acctID, args[0]))
 	if err != nil {
 		return fmt.Errorf("downloading media: %w", err)
 	}

cmd/message/media/list.go

@@ -29,7 +29,7 @@ func runList(cmd *cobra.Command, args []string) error {
 	}
 
 	var result interface{}
-	if err := client.Get(fmt.Sprintf("/users/%s/media", acctID), &result); err != nil {
+	if err := client.Get(cmd.Context(), fmt.Sprintf("/users/%s/media", acctID), &result); err != nil {
 		return fmt.Errorf("listing media: %w", err)
 	}
 

cmd/message/media/upload.go

@@ -67,7 +67,7 @@ func runUpload(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	if err := client.PutRaw(fmt.Sprintf("/users/%s/media/%s", acctID, mediaID), data, ct); err != nil {
+	if err := client.PutRaw(cmd.Context(), fmt.Sprintf("/users/%s/media/%s", acctID, mediaID), data, ct); err != nil {
 		return fmt.Errorf("uploading media: %w", err)
 	}