Skip to content

REQ-O-008: --quiet / --verbose / --debug Verbosity Flags

Tier: Opt-In | Priority: P1

Source: §4 Verbosity & Token Cost

Addresses: Severity: Medium / Token Spend: High / Time: Low / Context: High

Description

The framework MUST provide --quiet (suppress all stderr; stdout JSON only), --verbose (progress messages on stderr), and --debug (full debug trace on stderr) as standard flags on every command. These MUST override the auto-quiet behavior (REQ-F-038). The verbosity levels MUST be mutually exclusive. In --debug mode, all framework-internal operations (config loading, lock acquisition, HTTP requests) MUST be logged to stderr.

Acceptance Criteria

  • --quiet produces zero bytes on stderr (even for warnings)
  • --verbose produces progress messages on stderr and the JSON result on stdout
  • --debug produces full diagnostic trace on stderr including all HTTP requests and config resolution steps
  • Passing --verbose with CI=true overrides the auto-quiet mode

Schema

No dedicated schema type — verbosity flags govern stderr content only. In --debug mode, meta.debug fields may be added to the ResponseEnvelope by framework internals, but no new top-level schema type is defined.

Wire Format

Quiet mode — no stderr output:

$ tool deploy --target staging --quiet --output json

{
  "ok": true,
  "data": { "id": "deploy-42", "status": "complete" },
  "error": null,
  "warnings": [],
  "meta": { "duration_ms": 340 }
}

Debug mode — stderr diagnostic trace, stdout unchanged:

$ tool deploy --target staging --debug --output json

stderr:

[DEBUG] Loading config from /home/user/.config/tool/config.yaml
[DEBUG] HTTP POST https://api.example.com/deploys → 201 Created (142ms)
[DEBUG] Lock acquired: /tmp/tool.lock (pid 18432)

stdout:

{
  "ok": true,
  "data": { "id": "deploy-42", "status": "complete" },
  "error": null,
  "warnings": [],
  "meta": { "duration_ms": 340, "debug": { "config_file": "/home/user/.config/tool/config.yaml" } }
}

Example

The framework registers all three verbosity flags globally at opt-in time.

app = Framework("tool")
app.enable_verbosity_flags()

# tool deploy --quiet       →  zero stderr bytes
# tool deploy --verbose     →  progress on stderr, JSON on stdout
# tool deploy --debug       →  full trace on stderr, meta.debug in JSON
Requirement Tier Relationship
REQ-F-038 F Provides: auto-quiet baseline that --verbose and --debug override
REQ-F-006 F Enforces: diagnostic output stays on stderr, JSON stays on stdout
REQ-F-051 F Enforces: secrets are redacted even in --debug output
REQ-O-012 O Composes: heartbeat messages respect --quiet suppression