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

Author: odsod

AGENTS.md

@@ -32,6 +32,40 @@ This separation lets consumers embed the CLI in a larger tool or swap the storag
 
 The Mapon API uses a single API key for all requests. The key is stored in the credential 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.WithHTTPClient(&http.Client{
+        Transport: &mapon.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/mapon/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"
 )
@@ -24,13 +25,19 @@ type Option func(*config)
 
 type config struct {
 	credentialStore Store
+	httpClient      *http.Client
 }
 
 // WithCredentialStore sets the credential store.
 func WithCredentialStore(s Store) Option {
 	return func(c *config) { c.credentialStore = s }
 }
 
+// WithHTTPClient sets the base HTTP client passed to the SDK.
+func WithHTTPClient(c *http.Client) Option {
+	return func(cfg *config) { cfg.httpClient = c }
+}
+
 // FileStore is a JSON file-backed store.
 type FileStore struct {
 	path string

cli/command.go

@@ -25,7 +25,6 @@ func NewCommand(opts ...Option) *cobra.Command {
 		Use:   "mapon",
 		Short: "Mapon API CLI",
 	}
-	cmd.PersistentFlags().Bool("debug", false, "Enable debug mode")
 
 	cmd.AddGroup(&cobra.Group{ID: "units", Title: "Units"})
 	cmd.AddCommand(newListUnitsCommand(&cfg))
@@ -138,7 +137,6 @@ func newLogoutCommand(cfg *config) *cobra.Command {
 // --- Client ---
 
 func newClient(cmd *cobra.Command, cfg *config) (*mapon.Client, error) {
-	debug, _ := cmd.Root().PersistentFlags().GetBool("debug")
 	var creds Credentials
 	if cfg.credentialStore != nil {
 		if err := cfg.credentialStore.Read(&creds); err != nil {
@@ -148,11 +146,12 @@ func newClient(cmd *cobra.Command, cfg *config) (*mapon.Client, error) {
 			return nil, fmt.Errorf("read credentials: %w", err)
 		}
 	}
-	return mapon.NewClient(
-		cmd.Context(),
-		mapon.WithDebug(debug),
-		mapon.WithAPIKey(creds.APIKey),
-	)
+	var opts []mapon.ClientOption
+	if cfg.httpClient != nil {
+		opts = append(opts, mapon.WithHTTPClient(cfg.httpClient))
+	}
+	opts = append(opts, mapon.WithAPIKey(creds.APIKey))
+	return mapon.NewClient(cmd.Context(), opts...)
 }
 
 // --- Units ---

cli/go.mod

@@ -0,0 +1,18 @@
+module github.com/way-platform/mapon-go/cli
+
+go 1.25.0
+
+require (
+	github.com/spf13/cobra v1.10.2
+	github.com/way-platform/mapon-go v0.0.0
+	golang.org/x/term v0.41.0
+	google.golang.org/protobuf v1.36.11
+)
+
+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/mapon-go => ../

cli/go.sum

@@ -0,0 +1,18 @@
+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/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.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

client.go

@@ -32,7 +32,7 @@ func NewClient(ctx context.Context, opts ...ClientOption) (*Client, error) {
 // clientConfig configures a [Client].
 type clientConfig struct {
 	apiKey       string
-	debug        bool
+	httpClient   *http.Client
 	retryCount   int
 	timeout      time.Duration
 	interceptors []func(http.RoundTripper) http.RoundTripper
@@ -62,10 +62,11 @@ func WithAPIKey(apiKey string) ClientOption {
 	}
 }
 
-// WithDebug toggles debug mode (request/response dumps to stderr).
-func WithDebug(debug bool) ClientOption {
+// WithHTTPClient sets the base HTTP client for the SDK client.
+// The client's transport is used as the innermost transport in the chain.
+func WithHTTPClient(httpClient *http.Client) ClientOption {
 	return func(config *clientConfig) {
-		config.debug = debug
+		config.httpClient = httpClient
 	}
 }
 
@@ -91,9 +92,15 @@ 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}
+	var transport http.RoundTripper = http.DefaultTransport
+	timeout := cfg.timeout
+	if cfg.httpClient != nil {
+		if cfg.httpClient.Transport != nil {
+			transport = cfg.httpClient.Transport
+		}
+		if cfg.httpClient.Timeout > 0 {
+			timeout = cfg.httpClient.Timeout
+		}
 	}
 	if cfg.apiKey != "" {
 		transport = &apiKeyTransport{
@@ -114,7 +121,7 @@ func (c *Client) httpClient(cfg clientConfig) *http.Client {
 		}
 	}
 	return &http.Client{
-		Timeout:   cfg.timeout,
+		Timeout:   timeout,
 		Transport: transport,
 	}
 }

cmd/mapon/go.mod

@@ -6,7 +6,8 @@ require (
 	charm.land/fang/v2 v2.0.1
 	charm.land/lipgloss/v2 v2.0.2
 	github.com/adrg/xdg v0.5.3
-	github.com/way-platform/mapon-go v0.0.0-00010101000000-000000000000
+	github.com/way-platform/mapon-go v0.0.0
+	github.com/way-platform/mapon-go/cli v0.0.0-00010101000000-000000000000
 )
 
 require (
@@ -36,7 +37,10 @@ require (
 	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/term v0.41.0 // indirect
 	golang.org/x/text v0.31.0 // indirect
-	google.golang.org/protobuf v1.36.10 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
 )
 
-replace github.com/way-platform/mapon-go => ../..
+replace (
+	github.com/way-platform/mapon-go => ../..
+	github.com/way-platform/mapon-go/cli => ../../cli
+)

cmd/mapon/go.sum

@@ -74,8 +74,8 @@ 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/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
 golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
-google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
-google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

cmd/mapon/main.go

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

debug.go

@@ -9,17 +9,24 @@ import (
 	"os"
 )
 
-type debugTransport struct {
-	next http.RoundTripper
+// DebugTransport is a [http.RoundTripper] that dumps requests and responses to stderr.
+// The Enabled field supports lazy evaluation via a *bool, allowing it to be bound
+// to a flag that is parsed after the transport is constructed.
+type DebugTransport struct {
+	Enabled *bool
+	Next    http.RoundTripper
 }
 
-func (t *debugTransport) RoundTrip(request *http.Request) (*http.Response, error) {
+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
 	}
@@ -31,6 +38,13 @@ func (t *debugTransport) RoundTrip(request *http.Request) (*http.Response, error
 	return response, nil
 }
 
+func (t *DebugTransport) next() http.RoundTripper {
+	if t.Next != nil {
+		return t.Next
+	}
+	return http.DefaultTransport
+}
+
 func prettyPrintDump(w io.Writer, dump []byte, prefix string) {
 	var output bytes.Buffer
 	output.Grow(len(dump) * 2)