feat(cli): add WithHTTPClient injection, separate cli module

- export DebugTransport with lazy Enabled *bool for embedding
- add WithHTTPClient option, remove WithDebug from client
- move --debug flag from cli package to standalone main.go
- create separate cli/go.mod to prevent cobra leaking into SDK
- update cmd/mbz/go.mod to depend on cli submodule
- document embedding pattern in AGENTS.md

Author: odsod

AGENTS.md

@@ -45,6 +45,41 @@ The Mercedes-Benz API uses two auth methods depending on the endpoint:
 
 Both are stored in the credential store. The OAuth2 token is cached separately in the token store.
 
+### Embedding in a Parent CLI
+
+The CLI can be embedded as a subcommand in a larger tool (e.g. a unified `way` CLI). Key design rules:
+
+- **Never use `cmd.Root()`** — resolves to the parent CLI's root when embedded, breaking flag lookups. Use `cmd.Flags()` instead (works for both persistent and local flags).
+- **`WithHTTPClient`** — the parent injects an `*http.Client` via `cli.WithHTTPClient()`. The SDK layers (auth, retry) stack on top of the injected client's transport.
+- **`DebugTransport`** — exported in `debug.go` with a lazy `Enabled *bool` field. The parent owns the `--debug` flag and points `Enabled` at the flag variable. The transport checks the pointer at request time, solving the chicken-and-egg problem (transport constructed before flag parsing).
+
+```go
+var debug bool
+cmd := cli.NewCommand(
+    cli.WithCredentialStore(store),
+    cli.WithTokenStore(tokenStore),
+    cli.WithHTTPClient(&http.Client{
+        Transport: &mbz.DebugTransport{
+            Enabled: &debug,
+            Next:    http.DefaultTransport,
+        },
+    }),
+)
+cmd.PersistentFlags().BoolVar(&debug, "debug", false, "Enable debug logging")
+```
+
+### Module Structure
+
+Three separate Go modules prevent Cobra/CLI dependencies from leaking into the SDK library:
+
+```
+go.mod          # SDK client library (no cobra, no CLI deps)
+cli/go.mod      # CLI commands (depends on root SDK + cobra)
+cmd/mbz/go.mod  # Standalone binary (depends on cli module)
+```
+
+Consumers who only need the Go client import the root module without pulling in CLI dependencies.
+
 ### Conventions
 
 - Subcommands are organized by entity using `cobra.Group`

cli/cli.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"encoding/json"
 	"fmt"
+	"net/http"
 	"os"
 	"path/filepath"
 )
@@ -28,6 +29,7 @@ type Option func(*config)
 type config struct {
 	credentialStore Store
 	tokenStore      Store
+	httpClient      *http.Client
 }
 
 // WithCredentialStore sets the credential store.
@@ -40,6 +42,11 @@ func WithTokenStore(s Store) Option {
 	return func(c *config) { c.tokenStore = s }
 }
 
+// WithHTTPClient sets a custom [http.Client] for the SDK client.
+func WithHTTPClient(httpClient *http.Client) Option {
+	return func(c *config) { c.httpClient = httpClient }
+}
+
 // FileStore is a JSON file-backed store.
 type FileStore struct {
 	path string

cli/command.go

@@ -31,7 +31,6 @@ func NewCommand(opts ...Option) *cobra.Command {
 		Use:   "mbz",
 		Short: "Mercedes-Benz API CLI",
 	}
-	cmd.PersistentFlags().Bool("debug", false, "Enable debug mode")
 	cmd.AddGroup(&cobra.Group{ID: "vehicles", Title: "Vehicles"})
 	cmd.AddCommand(newListVehiclesCommand(&cfg))
 	cmd.AddCommand(newAssignVehiclesCommand(&cfg))
@@ -681,10 +680,6 @@ func newConsumeVehicleSignalsCommand(cfg *config) *cobra.Command {
 // Client constructors.
 
 func newOAuth2Client(cmd *cobra.Command, cfg *config) (*mbz.Client, error) {
-	debug, err := cmd.Root().PersistentFlags().GetBool("debug")
-	if err != nil {
-		return nil, err
-	}
 	var creds Credentials
 	if cfg.credentialStore != nil {
 		if err := cfg.credentialStore.Read(&creds); err != nil && !errors.Is(err, fs.ErrNotExist) {
@@ -703,19 +698,17 @@ func newOAuth2Client(cmd *cobra.Command, cfg *config) (*mbz.Client, error) {
 	if token.Expiry.Before(time.Now()) {
 		return nil, fmt.Errorf("invalid token, please login using `mbz auth login`")
 	}
-	return mbz.NewClient(
-		cmd.Context(),
-		mbz.WithDebug(debug),
+	opts := []mbz.ClientOption{
 		mbz.WithRegion(mbz.Region(creds.Region)),
 		mbz.WithOAuth2TokenSource(oauth2.StaticTokenSource(&token)),
-	)
+	}
+	if cfg.httpClient != nil {
+		opts = append(opts, mbz.WithHTTPClient(cfg.httpClient))
+	}
+	return mbz.NewClient(cmd.Context(), opts...)
 }
 
 func newClientWithAPIKey(cmd *cobra.Command, cfg *config) (*mbz.Client, error) {
-	debug, err := cmd.Root().PersistentFlags().GetBool("debug")
-	if err != nil {
-		return nil, err
-	}
 	var creds Credentials
 	if cfg.credentialStore != nil {
 		if err := cfg.credentialStore.Read(&creds); err != nil {
@@ -732,11 +725,13 @@ func newClientWithAPIKey(cmd *cobra.Command, cfg *config) (*mbz.Client, error) {
 			"no API key found, please login using `mbz auth login --api-key <api-key>`",
 		)
 	}
-	return mbz.NewClient(
-		cmd.Context(),
-		mbz.WithDebug(debug),
+	opts := []mbz.ClientOption{
 		mbz.WithAPIKey(creds.APIKey),
-	)
+	}
+	if cfg.httpClient != nil {
+		opts = append(opts, mbz.WithHTTPClient(cfg.httpClient))
+	}
+	return mbz.NewClient(cmd.Context(), opts...)
 }
 
 // Helpers.

cli/go.mod

@@ -0,0 +1,25 @@
+module github.com/way-platform/mbz-go/cli
+
+go 1.25.0
+
+toolchain go1.26.0
+
+require (
+	github.com/spf13/cobra v1.10.2
+	github.com/twmb/franz-go v1.20.7
+	github.com/way-platform/mbz-go v0.0.0-00010101000000-000000000000
+	golang.org/x/oauth2 v0.30.0
+	golang.org/x/term v0.41.0
+	google.golang.org/protobuf v1.36.6
+)
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/klauspost/compress v1.18.4 // indirect
+	github.com/pierrec/lz4/v4 v4.1.25 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/twmb/franz-go/pkg/kmsg v1.12.0 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+)
+
+replace github.com/way-platform/mbz-go => ../

cli/go.sum

@@ -0,0 +1,32 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
+github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/pierrec/lz4/v4 v4.1.25 h1:kocOqRffaIbU5djlIBr7Wh+cx82C0vtFb0fOurZHqD0=
+github.com/pierrec/lz4/v4 v4.1.25/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/twmb/franz-go v1.20.7 h1:P4MGSXJjjAPP3NRGPCks/Lrq+j+twWMVl1qYCVgNmWY=
+github.com/twmb/franz-go v1.20.7/go.mod h1:0bRX9HZVaoueqFWhPZNi2ODnJL7DNa6mK0HeCrC2bNU=
+github.com/twmb/franz-go/pkg/kmsg v1.12.0 h1:CbatD7ers1KzDNgJqPbKOq0Bz/WLBdsTH75wgzeVaPc=
+github.com/twmb/franz-go/pkg/kmsg v1.12.0/go.mod h1:+DPt4NC8RmI6hqb8G09+3giKObE6uD2Eya6CfqBpeJY=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI=
+golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
+golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/protobuf v1.36.6 h1:z1NpPI8ku2WgiWnf+t9wTPsn6eP1L7ksHUlkfLvd9xY=
+google.golang.org/protobuf v1.36.6/go.mod h1:jduwjTPXsFjZGTmRluh+L6NjiWu7pchiJ2/5YcXBHnY=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

client.go

@@ -51,7 +51,7 @@ type clientConfig struct {
 	clientSecret string
 	apiKey       string
 	tokenSource  oauth2.TokenSource
-	debug        bool
+	httpClient   *http.Client
 	retryCount   int
 	timeout      time.Duration
 	interceptors []func(http.RoundTripper) http.RoundTripper
@@ -110,10 +110,11 @@ func WithAPIKey(apiKey string) ClientOption {
 	}
 }
 
-// WithDebug toggles debug mode (request/response dumps to stderr).
-func WithDebug(debug bool) ClientOption {
+// WithHTTPClient sets a custom [http.Client] for the SDK client.
+// The client's transport is used as the base transport in the middleware chain.
+func WithHTTPClient(httpClient *http.Client) ClientOption {
 	return func(config *clientConfig) {
-		config.debug = debug
+		config.httpClient = httpClient
 	}
 }
 
@@ -140,8 +141,8 @@ func WithInterceptor(interceptor func(http.RoundTripper) http.RoundTripper) Clie
 
 func (c *Client) httpClient(cfg clientConfig) *http.Client {
 	transport := http.DefaultTransport
-	if cfg.debug {
-		transport = &debugTransport{next: transport}
+	if cfg.httpClient != nil && cfg.httpClient.Transport != nil {
+		transport = cfg.httpClient.Transport
 	}
 	if cfg.tokenSource != nil {
 		transport = &oauth2.Transport{

cmd/mbz/go.mod

@@ -7,6 +7,7 @@ require (
 	charm.land/lipgloss/v2 v2.0.2
 	github.com/adrg/xdg v0.5.3
 	github.com/way-platform/mbz-go v0.0.0-00010101000000-000000000000
+	github.com/way-platform/mbz-go/cli v0.0.0-00010101000000-000000000000
 )
 
 require (
@@ -44,4 +45,7 @@ require (
 	google.golang.org/protobuf v1.36.10 // indirect
 )
 
-replace github.com/way-platform/mbz-go => ../..
+replace (
+	github.com/way-platform/mbz-go => ../..
+	github.com/way-platform/mbz-go/cli => ../../cli
+)

cmd/mbz/main.go

@@ -3,21 +3,28 @@ package main
 import (
 	"context"
 	"image/color"
+	"net/http"
 	"os"
 
 	"charm.land/fang/v2"
 	"charm.land/lipgloss/v2"
 	"github.com/adrg/xdg"
+	"github.com/way-platform/mbz-go"
 	"github.com/way-platform/mbz-go/cli"
 )
 
 func main() {
 	credPath, _ := xdg.ConfigFile("mbz-go/credentials.json")
 	tokenPath, _ := xdg.ConfigFile("mbz-go/token.json")
+	var debug bool
 	cmd := cli.NewCommand(
 		cli.WithCredentialStore(cli.NewFileStore(credPath)),
 		cli.WithTokenStore(cli.NewFileStore(tokenPath)),
+		cli.WithHTTPClient(&http.Client{
+			Transport: &mbz.DebugTransport{Enabled: &debug},
+		}),
 	)
+	cmd.PersistentFlags().BoolVar(&debug, "debug", false, "Enable debug mode")
 	if err := fang.Execute(
 		context.Background(),
 		cmd,

debug.go

@@ -9,17 +9,34 @@ import (
 	"os"
 )
 
-type debugTransport struct {
-	next http.RoundTripper
+// DebugTransport is a [http.RoundTripper] that dumps requests and responses to stderr.
+// When Enabled is non-nil, it checks the pointed-to bool on each request,
+// allowing lazy binding to a CLI flag.
+type DebugTransport struct {
+	// Enabled controls whether debug output is active.
+	// When nil, debug output is always active.
+	Enabled *bool
+	// Next is the underlying transport. When nil, [http.DefaultTransport] is used.
+	Next http.RoundTripper
 }
 
-func (t *debugTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+func (t *DebugTransport) next() http.RoundTripper {
+	if t.Next != nil {
+		return t.Next
+	}
+	return http.DefaultTransport
+}
+
+func (t *DebugTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+	if t.Enabled != nil && !*t.Enabled {
+		return t.next().RoundTrip(request)
+	}
 	requestDump, err := httputil.DumpRequestOut(request, true)
 	if err != nil {
 		return nil, fmt.Errorf("failed to dump request for debug: %w", err)
 	}
 	prettyPrintDump(os.Stderr, requestDump, "> ")
-	response, err := t.next.RoundTrip(request)
+	response, err := t.next().RoundTrip(request)
 	if err != nil {
 		return nil, err
 	}

go.mod

@@ -5,18 +5,6 @@ go 1.25.0
 toolchain go1.26.0
 
 require (
-	github.com/spf13/cobra v1.10.2
-	github.com/twmb/franz-go v1.20.7
 	golang.org/x/oauth2 v0.30.0
-	golang.org/x/term v0.41.0
 	google.golang.org/protobuf v1.36.6
 )
-
-require (
-	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/klauspost/compress v1.18.4 // indirect
-	github.com/pierrec/lz4/v4 v4.1.25 // indirect
-	github.com/spf13/pflag v1.0.9 // indirect
-	github.com/twmb/franz-go/pkg/kmsg v1.12.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
-)