fix: Display help text on stdout instead of stderr to prevent red color

[konard]

Summary

Fixed the color issue with help text when calling agent auth without a subcommand.

Problem

When running agent auth without specifying a subcommand (like login, logout, etc.), the help text was appearing in red color in terminals. This happened because the help text was being written to stderr using console.error(), and many terminals display stderr output in red by default.

Solution

Changed the fail handler in src/index.js to write validation errors and help text to stdout using console.log() instead of console.error(). This ensures the help text appears in normal color since it's informational, not an actual error.

Additionally, the fix includes stripping ANSI color codes from the output using stripAnsi() to ensure clean, colorless help text regardless of any formatting that yargs might apply.

Research: Is Help Display an Error or Success?

To validate this approach, I researched how popular CLI tools handle this scenario:

Popular CLI Tools Behavior

Tool	No Subcommand	Destination
git	2126 bytes stdout, 0 bytes stderr	✅ STDOUT
gh (GitHub CLI)	2442 bytes stdout, 0 bytes stderr	✅ STDOUT
npm	1268 bytes stdout, 0 bytes stderr	✅ STDOUT
agent auth (after fix)	2242 bytes stdout, 0 bytes stderr	✅ STDOUT

Invalid Subcommand vs No Subcommand

Leading tools distinguish between:

• Help display (no args) → STDOUT (informational)
• Error messages (invalid args) → STDERR (actual error)

Example with git:

• git (no subcommand) → STDOUT (2126 bytes help text)
• git invalidcmd (invalid subcommand) → STDERR (61 bytes error)

Conclusion

Our approach follows industry standards:

1. Industry Standard: Leading CLI tools (git, gh, npm) display help on stdout when called without subcommands
2. User Intent: When users type agent auth, they're seeking information, not encountering an error
3. Terminal Behavior: Many terminals display stderr in red, which is inappropriate for help text
4. Semantic Correctness: Help display is informational (stdout), not an error condition (stderr)

See detailed research findings in experiments/cli-help-research/RESEARCH-FINDINGS.md

Changes

• Modified src/index.js line 639-640: Changed console.error() to console.log() with stripAnsi() for validation error messages and help text
• Added test scripts in experiments/cli-help-research/ folder to verify the fix and research CLI tool behavior

Testing

Verified that:

• ✅ Help text for agent auth now goes to stdout (not stderr)
• ✅ Help text appears in normal color (not red)
• ✅ Behavior matches industry standards (git, gh, npm)
• ✅ All local CI checks pass (lint, format, file-size)
• ✅ The fix applies to all commands (auth, mcp, etc.)

Fixes #77

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $2.931474 USD
• Calculated by Anthropic: unknown
• Difference: unknown
  📎 Log file uploaded as GitHub Gist (489KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

How other CLI tools handle these cases? Is display of help is error or success?

[konard]

🤖 AI Work Session Started

Starting automated work session at 2025-12-21T20:07:35.618Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

Answer: Help display should go to STDOUT (success case)

I researched how popular CLI tools handle this scenario. Here are the findings:

Popular CLI Tools Behavior

When called without a subcommand, these tools display help on stdout:

git        → stdout: 2126 bytes, stderr: 0 bytes ✅ STDOUT
gh         → stdout: 2442 bytes, stderr: 0 bytes ✅ STDOUT  
npm        → stdout: 1268 bytes, stderr: 0 bytes ✅ STDOUT
agent auth → stdout: 2242 bytes, stderr: 0 bytes ✅ STDOUT (after our fix)

Invalid Subcommand vs No Subcommand

CLI tools distinguish between these two cases:

Case 1: No subcommand (user needs help)

• git → STDOUT (2126 bytes help text)
• gh → STDOUT (2442 bytes help text)

Case 2: Invalid subcommand (actual error)

• git invalidcmd → STDERR (61 bytes error)
• gh invalidcmd → STDERR (378 bytes error)

Why STDOUT is Correct

1. Industry Standard: git, gh, and npm all use stdout for help display
2. Semantic Correctness: Help display is informational (stdout), not an error condition (stderr)
3. User Intent: When typing agent auth, users are seeking information, not encountering an error
4. Terminal Behavior: Many terminals show stderr in red, which is inappropriate for help text

Conclusion

Help display is a success case - the tool is successfully showing the user what they need. Our fix aligns with how leading CLI tools (git, GitHub CLI, npm) handle this scenario.

Full research findings are documented in experiments/cli-help-research/RESEARCH-FINDINGS.md

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $1.170437 USD
• Calculated by Anthropic: $0.877703 USD
• Difference: $-0.292734 (-25.01%)
  📎 Log file uploaded as GitHub Gist (237KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.