Mirror b6eb8a4 (2026-03-18)

Author: Prompsit CI

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file.
 - `/publish` skill: commit+push only, npm publish handled by CI
 
 ### Added
+- `--verbose` / `-v` CLI flag — enables debug logging to stderr for troubleshooting
 - `fix:all` npm script — ESLint autofix + Prettier in one command
 - `/changelog` skill for maintaining CHANGELOG.md
 - GitHub Release auto-creation from CHANGELOG.md Unreleased section

docs/reference/guides/logging-policy.md

@@ -154,7 +154,20 @@ CLI/REPL entry point
 
 ---
 
-## 6. Handler Output Formats
+## 6. CLI Verbosity Flag
+
+| Flag | Console Level | Use Case |
+|------|--------------|----------|
+| _(none)_ | config `log_level` (default: `"warn"`) | Normal usage |
+| `--verbose` / `-v` | `"debug"` | Troubleshooting |
+
+**Precedence** (highest wins): `--verbose` > `PROMPSIT_CLI__LOG_LEVEL` env var > `config.toml` `[cli] log_level` > `"warn"` default.
+
+The flag is pre-scanned from `process.argv` before `setupLogging()`, so it captures all startup diagnostics. File logging (`~/.prompsit/debug.log`) always captures DEBUG regardless of this flag.
+
+---
+
+## 7. Handler Output Formats
 
 | Handler | Destination | Format | Example |
 |---------|------------|--------|---------|
@@ -174,7 +187,7 @@ CLI/REPL entry point
 
 ---
 
-## 7. Message Conventions
+## 8. Message Conventions
 
 | Rule | Good | Bad |
 |------|------|-----|
@@ -185,7 +198,7 @@ CLI/REPL entry point
 
 ---
 
-## 8. console.log vs logger
+## 9. console.log vs logger
 
 | Output Type | Tool | Destination |
 |-------------|------|-------------|
@@ -200,7 +213,7 @@ CLI/REPL entry point
 
 ---
 
-## 9. Anti-Patterns & Fixes
+## 10. Anti-Patterns & Fixes
 
 | Anti-Pattern | Fix |
 |-------------|-----|
@@ -222,7 +235,7 @@ CLI/REPL entry point
 - New standard metadata fields
 - Logging infrastructure changes (new handlers)
 
-**Last Updated:** 2026-02-15
+**Last Updated:** 2026-03-18
 
 ## Sources
 

src/index.ts

@@ -23,7 +23,11 @@ const isEntryPoint =
   stripExt(fileURLToPath(import.meta.url)) === stripExt(realpathSync(process.argv[1] ?? ""));
 if (isEntryPoint) {
   setupSignalHandlers();
-  setupLogging();
+
+  // Pre-scan argv for --verbose before logging init (captures ALL startup logs)
+  const userArgs = process.argv.slice(2);
+  const isVerbose = userArgs.includes("--verbose") || userArgs.includes("-v");
+  setupLogging(isVerbose ? "debug" : undefined);
   process.on("exit", shutdownLogging);
 
   // Skill sync: deploy AI agent skills on launch (skip --help/--version quick-exit paths)
@@ -40,7 +44,8 @@ if (isEntryPoint) {
   }
 
   // See API-503: No-args detection — enter REPL mode when no command specified
-  const hasCommand = process.argv.length > 2;
+  // Check for non-flag args (flags like --verbose should not prevent REPL entry)
+  const hasCommand = userArgs.some((a) => !a.startsWith("-"));
 
   if (hasCommand) {
     // Wrap in trace context: single trace_id for entire CLI command execution

src/logging/setup.ts

@@ -29,17 +29,17 @@ export function silenceConsole(): void {
 /**
  * Initialize logging with pino multistream: console (pretty), file, and optional Loki.
  *
- * Console level follows cli.log_level from config.
+ * Console level: consoleOverride (CLI flag) > cli.log_level (config) > "warn" (default).
  * File stream always captures DEBUG (full diagnostics).
  * Root pino level = "debug" (lowest stream level, required by multistream).
  */
-export function setupLogging(): void {
+export function setupLogging(consoleOverride?: LogLevel): void {
   if (_initialized) return;
   _initialized = true;
 
   const settings = getSettings();
   const settingsDiagnostics = getSettingsDiagnostics();
-  const configLevel = settings.cli.log_level as LogLevel;
+  const configLevel = consoleOverride ?? (settings.cli.log_level as LogLevel);
 
   // 1. Console stream: pino-pretty → gated stderr writable
   const gatedStderr = new Writable({

src/program.ts

@@ -39,6 +39,7 @@ program.configureHelp({
 
 program.helpOption("-h, --help", "Show this help");
 program.version(getVersion(), "-V, --version", "Show version number");
+program.option("-v, --verbose", "Enable debug logging to stderr");
 
 // --- Grouped commands ---