rainyun-cli/docs/spec/2026-07-28-verbose-debug-design.md

Verbose/Debug Mode Design

Date: 2026-07-28 Status: Approved

Goal

Wire up the existing --debug flag (currently unused) and add --verbose as an alias. When enabled, print detailed runtime and HTTP request information to stderr.

Scope

4 files modified, 0 new files.

Changes

1. internal/provider/provider.go — ProviderConfig

Add Debug bool field to ProviderConfig:

type ProviderConfig struct {
    APIKey          string
    AccessKeyID     string
    AccessKeySecret string
    Endpoint        string
    Debug           bool
}

2. cmd/cli/root.go — Flag + Runtime Info

• Register --verbose as alias for --debug (both set flagDebug)
• In PersistentPreRunE, when debug is on, print to stderr:
  • Provider name
  • Config file path
  • Output format

3. internal/provider/rainyun/client.go — HTTP Logging

• Add debug bool field to client struct
• Update newClient(endpoint, apiKey string, debug bool) signature
• In do(), when c.debug is true, print to os.Stderr:
  • Request: > METHOD /path + request body (if any)
  • Response: < StatusCode StatusText Duration + response body

4. internal/provider/rainyun/rainyun.go — Pass Debug

• New() passes cfg.Debug to newClient()

Output Format

All debug output goes to stderr to avoid polluting stdout data pipeline.

[debug] provider: rainyun
[debug] config: /Users/user/.config/ry/config.json
[debug] output: table
[debug] > GET /api/v2/servers
[debug] < 200 OK 123ms
[debug] {"code":200,"data":[...]}

Files

File	Change
internal/provider/provider.go	Add Debug to ProviderConfig
cmd/cli/root.go	Wire --verbose, print runtime info
internal/provider/rainyun/client.go	HTTP request/response logging
internal/provider/rainyun/rainyun.go	Pass cfg.Debug to client