# 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`:

```go
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 |