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/rfms/go.mod to depend on cli submodule
- document embedding pattern in AGENTS.md

Author: odsod

AGENTS.md

@@ -37,6 +37,41 @@ The rFMS standard is implemented by multiple OEMs, each with their own auth:
 
 The `Credentials` struct stores the active provider alongside the provider-specific fields.
 
+### 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: &rfms.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/rfms/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`

auth_scania.go

@@ -37,8 +37,9 @@ type ScaniaAuthConfig struct {
 	// Timeout is the timeout for a request.
 	Timeout time.Duration
 
-	// Debug is whether to enable debug logging.
-	Debug bool
+	// HTTPClient is the base HTTP client whose transport is used as the
+	// innermost layer. When nil, [http.DefaultTransport] is used.
+	HTTPClient *http.Client
 }
 
 // TokenSource returns an oauth2.TokenSource that retrieves tokens using
@@ -169,10 +170,8 @@ func (s *scaniaTokenSource) newRequest(method, path string, body io.Reader) (*ht
 // httpClient returns the HTTP client to use, with retry transport if none specified.
 func (s *scaniaTokenSource) httpClient() *http.Client {
 	transport := http.DefaultTransport
-	if s.config.Debug {
-		transport = &debugTransport{
-			next: transport,
-		}
+	if s.config.HTTPClient != nil && s.config.HTTPClient.Transport != nil {
+		transport = s.config.HTTPClient.Transport
 	}
 	if s.config.MaxRetries > 0 {
 		transport = &retryTransport{

cli/cli.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"encoding/json"
 	"fmt"
+	"net/http"
 	"os"
 	"path/filepath"
 )
@@ -32,6 +33,7 @@ type Option func(*config)
 type config struct {
 	credentialStore Store
 	tokenStore      Store
+	httpClient      *http.Client
 }
 
 // WithCredentialStore sets the credential store.
@@ -44,6 +46,11 @@ func WithTokenStore(s Store) Option {
 	return func(c *config) { c.tokenStore = s }
 }
 
+// WithHTTPClient sets the base [http.Client] passed to 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

@@ -5,7 +5,6 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
-	"log/slog"
 	"os"
 	"time"
 
@@ -26,17 +25,6 @@ func NewCommand(opts ...Option) *cobra.Command {
 		Use:   "rfms",
 		Short: "rFMS CLI",
 	}
-	cmd.PersistentFlags().Bool("debug", false, "Enable debug logging")
-	cmd.PersistentPreRunE = func(cmd *cobra.Command, _ []string) error {
-		level := slog.LevelInfo
-		if cmd.Root().PersistentFlags().Changed("debug") {
-			level = slog.LevelDebug
-		}
-		slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
-			Level: level,
-		})))
-		return nil
-	}
 	cmd.AddGroup(&cobra.Group{ID: "rfms", Title: "rFMS Commands"})
 	cmd.AddCommand(newVehiclesCommand(&cfg))
 	cmd.AddCommand(newVehiclePositionsCommand(&cfg))
@@ -352,8 +340,7 @@ func newVehicleStatusesCommand(cfg *config) *cobra.Command {
 	return cmd
 }
 
-func newClient(cmd *cobra.Command, cfg *config) (*rfms.Client, error) {
-	debug, _ := cmd.Root().PersistentFlags().GetBool("debug")
+func newClient(_ *cobra.Command, cfg *config) (*rfms.Client, error) {
 	var creds Credentials
 	if cfg.credentialStore != nil {
 		if err := cfg.credentialStore.Read(&creds); err != nil {
@@ -363,6 +350,10 @@ func newClient(cmd *cobra.Command, cfg *config) (*rfms.Client, error) {
 			return nil, fmt.Errorf("read credentials: %w", err)
 		}
 	}
+	var opts []rfms.ClientOption
+	if cfg.httpClient != nil {
+		opts = append(opts, rfms.WithHTTPClient(cfg.httpClient))
+	}
 	switch creds.Provider {
 	case rfms.BrandScania:
 		var token oauth2.Token
@@ -381,17 +372,17 @@ func newClient(cmd *cobra.Command, cfg *config) (*rfms.Client, error) {
 				"session expired, please login again using `rfms auth login scania`",
 			)
 		}
-		return rfms.NewClient(
-			rfms.WithDebug(debug),
+		opts = append(opts,
 			rfms.WithBaseURL(rfms.ScaniaBaseURL),
 			rfms.WithVersion(rfms.V4),
 			rfms.WithTokenSource(oauth2.StaticTokenSource(&token)),
 		)
+		return rfms.NewClient(opts...)
 	case rfms.BrandVolvoTrucks:
-		return rfms.NewClient(
-			rfms.WithDebug(debug),
+		opts = append(opts,
 			rfms.WithVolvoTrucks(creds.Username, creds.Password),
 		)
+		return rfms.NewClient(opts...)
 	default:
 		return nil, fmt.Errorf("unknown provider: %s", creds.Provider)
 	}

cli/go.mod

@@ -0,0 +1,21 @@
+module github.com/way-platform/rfms-go/cli
+
+go 1.25.0
+
+toolchain go1.26.0
+
+require (
+	github.com/spf13/cobra v1.10.2
+	github.com/way-platform/rfms-go v0.14.0
+	golang.org/x/oauth2 v0.31.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/spf13/pflag v1.0.9 // indirect
+	golang.org/x/sys v0.42.0 // indirect
+)
+
+replace github.com/way-platform/rfms-go => ../

cli/go.sum

@@ -0,0 +1,20 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+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=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/oauth2 v0.31.0 h1:8Fq0yVZLh4j4YA47vHKFTa9Ew5XIrCP8LC6UeNZnLxo=
+golang.org/x/oauth2 v0.31.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
+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=
+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

@@ -20,7 +20,7 @@ type ClientConfig struct {
 	baseURL      string
 	apiVersion   Version
 	retryCount   int
-	debug        bool
+	httpClient   *http.Client
 	timeout      time.Duration
 	tokenSource  oauth2.TokenSource
 	username     string
@@ -67,12 +67,10 @@ func NewClient(opts ...ClientOption) (*Client, error) {
 
 // httpClient creates a new HTTP client with the given configuration.
 func (c *Client) httpClient(cfg ClientConfig) *http.Client {
+	// Use injected client's transport as base, or fall back to default.
 	transport := http.DefaultTransport
-	// Add debug transport if debug is enabled.
-	if cfg.debug {
-		transport = &debugTransport{
-			next: transport,
-		}
+	if cfg.httpClient != nil && cfg.httpClient.Transport != nil {
+		transport = cfg.httpClient.Transport
 	}
 	// Add basic auth transport if username/password are configured
 	if cfg.username != "" && cfg.password != "" {
@@ -109,10 +107,12 @@ func (c *Client) httpClient(cfg ClientConfig) *http.Client {
 	}
 }
 
-// WithDebug sets the debug flag for the [Client].
-func WithDebug(debug bool) ClientOption {
+// WithHTTPClient sets the base [http.Client] whose transport is used as the
+// innermost layer of the transport chain. This is useful for injecting a
+// [DebugTransport] or custom TLS configuration.
+func WithHTTPClient(httpClient *http.Client) ClientOption {
 	return func(cc *ClientConfig) {
-		cc.debug = debug
+		cc.httpClient = httpClient
 	}
 }
 
@@ -168,7 +168,7 @@ func WithScania(clientID, clientSecret string) ClientOption {
 			WithTokenSource(ScaniaAuthConfig{
 				ClientID:     clientID,
 				ClientSecret: clientSecret,
-				Debug:        cc.debug,
+				HTTPClient:   cc.httpClient,
 				MaxRetries:   cc.retryCount,
 				Timeout:      cc.timeout,
 			}.TokenSource(context.Background())),

cmd/rfms/go.mod

@@ -9,6 +9,7 @@ require (
 	charm.land/lipgloss/v2 v2.0.2
 	github.com/adrg/xdg v0.5.3
 	github.com/way-platform/rfms-go v0.14.0
+	github.com/way-platform/rfms-go/cli v0.0.0
 )
 
 require (
@@ -42,4 +43,7 @@ require (
 	google.golang.org/protobuf v1.36.9 // indirect
 )
 
-replace github.com/way-platform/rfms-go => ../../
+replace (
+	github.com/way-platform/rfms-go => ../../
+	github.com/way-platform/rfms-go/cli => ../../cli/
+)

cmd/rfms/main.go

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

debug.go

@@ -9,17 +9,35 @@ import (
 	"os"
 )
 
-type debugTransport struct {
-	next http.RoundTripper
+// DebugTransport is an [http.RoundTripper] that dumps HTTP requests and
+// responses to stderr. When Enabled is non-nil, logging is gated on the
+// pointed-to bool, allowing a CLI flag to be bound before the value is known.
+type DebugTransport struct {
+	// Enabled gates debug output. When nil, output is always enabled.
+	Enabled *bool
+	// Next is the underlying transport. Defaults to [http.DefaultTransport].
+	Next http.RoundTripper
 }
 
-func (t *debugTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+var _ http.RoundTripper = (*DebugTransport)(nil)
+
+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
 	}