Add context-aware requests and configurable timeout

Thread context.Context through the Metabase client and CLI so HTTP
requests can be cancelled and time-bounded consistently.

- Client request methods accept a context and build requests with
  http.NewRequestWithContext; report clear timeout/cancellation errors.
- Root context is cancelled on SIGINT/SIGTERM so commands abort on Ctrl+C.
- New --timeout flag (default 30s, 0 disables) bounds each command's
  API requests.
- Classify timeout and cancellation errors for --error-format json.

Closes #11

Author: andreagrandi

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Add `--timeout` flag and propagate request contexts so commands abort cleanly on Ctrl+C, with clear timeout and cancellation errors (#11)
 - Add `MB_SESSION_TOKEN` as an alternative authentication method for users without admin access to mint an API key; mutually exclusive with `MB_API_KEY` (#9)
 - Document changelog update workflow in `AGENTS.md` and add a pull request template prompting contributors to update `CHANGELOG.md` for user-visible changes (#20)
 - Move main package to `cmd/mb-cli` so `go install github.com/andreagrandi/mb-cli/cmd/mb-cli@latest` produces an `mb-cli` binary that matches the documented command name (#10)

README.md

@@ -62,6 +62,7 @@ export MB_REDACT_PII=false  # Disable PII redaction (enabled by default)
 | `--format`, `-f` | Output format: `json`, `table` | `json` |
 | `--verbose`, `-v` | Show request details on stderr | `false` |
 | `--redact-pii` | Redact PII values in query results | `true` |
+| `--timeout` | Timeout for a command's API requests (`0` disables) | `30s` |
 
 ### Database commands
 

internal/cli/card.go

@@ -66,7 +66,10 @@ func runCardList(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	cards, err := c.ListCards()
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	cards, err := c.ListCards(ctx)
 	if err != nil {
 		return err
 	}
@@ -85,7 +88,10 @@ func runCardGet(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	card, err := c.GetCard(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	card, err := c.GetCard(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -114,7 +120,10 @@ func runCardRun(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	result, err := c.RunCardWithParams(id, params)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	result, err := c.RunCardWithParams(ctx, id, params)
 	if err != nil {
 		return wrapParameterizedRunError(err)
 	}

internal/cli/context_embed.md

@@ -50,6 +50,7 @@ Set both environment variables (required):
 | `--verbose`, `-v` | bool | false | Show request details on stderr |
 | `--error-format` | string | `text` | Error output format: `text` or `json` |
 | `--redact-pii` | bool | `true` | Redact PII values in query results |
+| `--timeout` | duration | `30s` | Timeout for a command's API requests (`0` disables) |
 
 ## Command-Specific Flags
 

internal/cli/dashboard.go

@@ -120,7 +120,10 @@ func runDashboardList(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	dashboards, err := c.ListDashboards()
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	dashboards, err := c.ListDashboards(ctx)
 	if err != nil {
 		return err
 	}
@@ -149,7 +152,10 @@ func runDashboardGet(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	dashboard, err := c.GetDashboard(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	dashboard, err := c.GetDashboard(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -173,7 +179,10 @@ func runDashboardCards(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	dashboard, err := c.GetDashboard(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	dashboard, err := c.GetDashboard(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -248,7 +257,10 @@ func runDashboardRunCard(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	result, err := c.RunDashboardCard(dashboardID, dashcardID, cardID, params)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	result, err := c.RunDashboardCard(ctx, dashboardID, dashcardID, cardID, params)
 	if err != nil {
 		return wrapParameterizedRunError(err)
 	}
@@ -267,7 +279,10 @@ func runDashboardParamLookup(cmd *cobra.Command, dashboardArg string, requestedK
 		return err
 	}
 
-	dashboard, err := c.GetDashboard(dashboardID)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	dashboard, err := c.GetDashboard(ctx, dashboardID)
 	if err != nil {
 		return err
 	}
@@ -276,9 +291,9 @@ func runDashboardParamLookup(cmd *cobra.Command, dashboardArg string, requestedK
 
 	var values *client.ParameterValues
 	if search {
-		values, err = c.SearchDashboardParamValues(dashboardID, resolvedKey, query)
+		values, err = c.SearchDashboardParamValues(ctx, dashboardID, resolvedKey, query)
 	} else {
-		values, err = c.GetDashboardParamValues(dashboardID, resolvedKey)
+		values, err = c.GetDashboardParamValues(ctx, dashboardID, resolvedKey)
 	}
 	if err != nil {
 		return err

internal/cli/dashboard_analyze.go

@@ -1,6 +1,7 @@
 package cli
 
 import (
+	"context"
 	"fmt"
 	"io"
 	"os"
@@ -98,7 +99,10 @@ func runDashboardAnalyze(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	analysis, err := analyzeDashboard(c, id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	analysis, err := analyzeDashboard(ctx, c, id)
 	if err != nil {
 		return err
 	}
@@ -111,8 +115,8 @@ func runDashboardAnalyze(cmd *cobra.Command, args []string) error {
 	return formatDashboardAnalysisTable(os.Stdout, analysis)
 }
 
-func analyzeDashboard(c *client.Client, id int) (*dashboardAnalysis, error) {
-	dashboard, err := c.GetDashboard(id)
+func analyzeDashboard(ctx context.Context, c *client.Client, id int) (*dashboardAnalysis, error) {
+	dashboard, err := c.GetDashboard(ctx, id)
 	if err != nil {
 		return nil, err
 	}
@@ -166,7 +170,7 @@ func analyzeDashboard(c *client.Client, id int) (*dashboardAnalysis, error) {
 		entry.ParameterIDs = collectDashcardParameterIDs(dashCard)
 
 		if dashCard.CardID != nil {
-			fullCard, chain, baseCard, err := traceCardLineage(c, cardCache, *dashCard.CardID)
+			fullCard, chain, baseCard, err := traceCardLineage(ctx, c, cardCache, *dashCard.CardID)
 			if err != nil {
 				return nil, err
 			}
@@ -275,8 +279,8 @@ func collectDashcardParameterIDs(dashCard client.DashCard) []string {
 	return ids
 }
 
-func traceCardLineage(c *client.Client, cache map[int]*client.Card, cardID int) (*client.Card, []int, *client.Card, error) {
-	current, err := getAnalyzedCard(c, cache, cardID)
+func traceCardLineage(ctx context.Context, c *client.Client, cache map[int]*client.Card, cardID int) (*client.Card, []int, *client.Card, error) {
+	current, err := getAnalyzedCard(ctx, c, cache, cardID)
 	if err != nil {
 		return nil, nil, nil, err
 	}
@@ -291,7 +295,7 @@ func traceCardLineage(c *client.Client, cache map[int]*client.Card, cardID int)
 		chain = append(chain, *sourceCardID)
 		seen[*sourceCardID] = true
 
-		current, err = getAnalyzedCard(c, cache, *sourceCardID)
+		current, err = getAnalyzedCard(ctx, c, cache, *sourceCardID)
 		if err != nil {
 			return nil, nil, nil, err
 		}
@@ -300,12 +304,12 @@ func traceCardLineage(c *client.Client, cache map[int]*client.Card, cardID int)
 	return cache[cardID], chain, nil, nil
 }
 
-func getAnalyzedCard(c *client.Client, cache map[int]*client.Card, cardID int) (*client.Card, error) {
+func getAnalyzedCard(ctx context.Context, c *client.Client, cache map[int]*client.Card, cardID int) (*client.Card, error) {
 	if card, ok := cache[cardID]; ok {
 		return card, nil
 	}
 
-	card, err := c.GetCard(cardID)
+	card, err := c.GetCard(ctx, cardID)
 	if err != nil {
 		return nil, err
 	}

internal/cli/database.go

@@ -101,7 +101,10 @@ func runDatabaseList(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	databases, err := c.ListDatabases(false)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	databases, err := c.ListDatabases(ctx, false)
 	if err != nil {
 		return err
 	}
@@ -120,7 +123,10 @@ func runDatabaseGet(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	db, err := c.GetDatabase(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	db, err := c.GetDatabase(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -139,7 +145,10 @@ func runDatabaseMetadata(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	meta, err := c.GetDatabaseMetadata(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	meta, err := c.GetDatabaseMetadata(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -158,7 +167,10 @@ func runDatabaseFields(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	fields, err := c.GetDatabaseFields(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	fields, err := c.GetDatabaseFields(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -177,7 +189,10 @@ func runDatabaseSchemas(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	schemas, err := c.ListDatabaseSchemas(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	schemas, err := c.ListDatabaseSchemas(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -197,7 +212,10 @@ func runDatabaseSchema(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	tables, err := c.GetDatabaseSchema(id, schema)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	tables, err := c.GetDatabaseSchema(ctx, id, schema)
 	if err != nil {
 		return err
 	}

internal/cli/field.go

@@ -52,7 +52,10 @@ func runFieldGet(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	field, err := c.GetField(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	field, err := c.GetField(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -71,7 +74,10 @@ func runFieldSummary(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	summary, err := c.GetFieldSummary(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	summary, err := c.GetFieldSummary(ctx, id)
 	if err != nil {
 		return err
 	}
@@ -90,7 +96,10 @@ func runFieldValues(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	values, err := c.GetFieldValues(id)
+	ctx, cancel := requestContext(cmd)
+	defer cancel()
+
+	values, err := c.GetFieldValues(ctx, id)
 	if err != nil {
 		return err
 	}