Adopt Printing Press agent-native CLI conventions#10
Open
zgalant wants to merge 3 commits into
maincodehs/bool-cli:mainfrom
claude/align-cli-standards-3VTBycodehs/bool-cli:claude/align-cli-standards-3VTByCopy head branch name to clipboard
Open
Adopt Printing Press agent-native CLI conventions#10zgalant wants to merge 3 commits intomaincodehs/bool-cli:mainfrom claude/align-cli-standards-3VTBycodehs/bool-cli:claude/align-cli-standards-3VTByCopy head branch name to clipboard
zgalant wants to merge 3 commits into
maincodehs/bool-cli:mainfrom
claude/align-cli-standards-3VTBycodehs/bool-cli:claude/align-cli-standards-3VTByCopy head branch name to clipboard
Conversation
Adopt the standard agent-native flag set, typed exit codes, and auto-JSON-on-pipe behavior described at https://printingpress.dev/. - Global flags on every command: --json, --csv, --select, --compact, --quiet, --no-color, --no-input, --dry-run. - Auto-emit JSON when stdout is piped (no flag needed). - Typed exit codes: 0 success, 2 usage, 3 not found, 4 auth, 5 API, 7 rate limited. API client maps HTTP status accordingly. - Errors include a hint pointing at the offending flag/value or the remediation step so agents can self-correct in one retry. - New 'auth doctor' subcommand reports key presence, reachability, and authenticated-call validity as a structured check list. - Shared action wrapper (src/utils/action.js) plumbs global flags into every handler and turns CliError into the right exit code. - Status messages route to stderr; structured data to stdout, so pipelines like `bool list | jq` work without losing logs.
| healthy, | ||
| ...(healthy ? {} : { error: healthError }), | ||
| }); | ||
| if (shaped === undefined) return; |
There was a problem hiding this comment.
🔴 auth status silently exits 0 in structured output mode when API health check fails
When structured output is active (piped stdout, --json, or --csv), printData() returns undefined and auth status returns early at line 78 with exit code 0 — even when the health check has failed (healthy === false). The JSON payload contains "healthy": false and the error message, but the process exit code is 0 (success). This is inconsistent with auth doctor (src/commands/auth.js:128-130) which correctly sets process.exitCode = EXIT.AUTH in the same situation. An agent relying on exit codes (the core Printing Press convention this PR introduces) cannot detect the failure.
Suggested change
| if (shaped === undefined) return; | |
| if (shaped === undefined) { | |
| if (!healthy) process.exitCode = EXIT.API; | |
| return; | |
| } |
Was this helpful? React with 👍 or 👎 to provide feedback.
In JSON/CSV/piped mode auth status returned early after printing the payload, leaving exit code 0 even when the health check had failed. Set EXIT.API before returning, matching how auth doctor already handles the same case. Reported by Devin Review on PR #10.
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR refactors the bool-cli to follow Printing Press agent-native CLI conventions, enabling better integration with AI agents and programmatic tooling while maintaining a great human experience.
Summary
The CLI now supports structured output (JSON/CSV) by default when piped, typed exit codes for machine-readable error handling, and standard flags on every command. Status messages are written to stderr, structured data to stdout, allowing clean piping without losing log output.
Key Changes
Output & Formatting
src/utils/output.jsto support multiple output modes: human (default), JSON, CSV, and auto-detection when stdout is piped--json,--csv,--select, and--compactflags to all commands for structured output control✔ ✖ ℹ ⚠) now write to stderr; structured data to stdoutdata()function that returns shaped data for human rendering or emits JSON/CSV automaticallyError Handling & Exit Codes
src/utils/exit.jswith typed exit codes (USAGE=2, NOT_FOUND=3, AUTH=4, API=5, RATE_LIMITED=7)CliErrorclass to carry exit codes and contextual hintsCommand Wrapper & Global Flags
src/utils/action.jswithaction()wrapper that:--json,--dry-run, etc.bin/bool.js:--json,--csv,--select,--compact,--quiet,--no-color,--no-input,--dry-runCommand Refactoring
action()to enable error handling and output configurationerror()+process.exit(1)patterns withusage()orCliErrorthrowslistBools,createBool, etc.) into command actions for clarity--dry-runsupport tocreate,update,delete,deploy,shipit,claim, andskillcommandsconfirm()to throwCliErrorwhen--no-inputis set instead of prompting--no-inputsupport toauth loginandauth statuscommandsauth doctorcommand for diagnosing auth + API connectivityAPI Error Handling
src/utils/api.jsto throwCliErrorwith appropriate exit codes based on HTTP statusDocumentation
--selectfor field filteringNotable Implementation Details
--csv→--json→ piped stdout → human (table/text)data()returnsundefinedwhen structured output is active (caller skips human rendering), or returns shaped data for human renderinglistFooter()prints "Showing N of M results" hint only in human mode--selectand--compactwork with any structured output formatCliError.hintfor agent self-correction--quietflag--no-colorandNO_COLORenvironment variablehttps://claude.ai/code/session_012nFFfAmPiCZBm8zJRoKrru