OfflineCreator CLI JSON output and exit-code handling

Separate machine output from diagnostics

Successful `models`, `balance`, and `generate` paths pass their values through `JSON.stringify(value, null, 2)` and write that formatted JSON to stdout. Usage failures write a message to stderr and return status 1. The executable assigns the parser's result to `process.exitCode`, while rejected errors are printed to stderr and also set status 1. Build automation around that split: capture stdout for parsing, preserve stderr for an operator, and check the process exit code before trusting either stream.

Do not merge the two streams before classification. A wrapper that combines stderr usage text with stdout can create invalid JSON while hiding whether the failure came from invocation, authentication, transport, or the service. Preserve the raw streams separately, then emit a smaller internal result with the command family, exit status, parsed payload or diagnostic category, and package version.

Know which outcomes are parser failures

The parser returns 1 when `generate` lacks a model or prompt and when an unknown command is supplied. Help forms return 0. Network, authentication, and service errors can reject above this return-value layer and are converted to a nonzero process exit by the package entry point. Do not collapse all of these cases into “bad JSON”; preserve the diagnostic and operation name.

Capture three values independently: stdout bytes, stderr bytes, and the process status. A missing model or prompt should follow the documented usage-failure branch, while `help`, `--help`, and `-h` are successful informational branches. Preserve that distinction so an operator can tell invalid invocation from an intentional help probe.

Parse defensively without scraping prose

Redirect stdout to a file or pipe it directly to a JSON parser only after the command succeeds. Do not scrape the help screen, because an unknown command prints help and fails. Check required fields for the command you ran rather than assuming one global response schema: model listings, credit responses, started generations, and waited generations are different payloads. Treat extra fields as forward-compatible data and missing required fields as a controlled failure.

Parse stdout only after a zero status, then validate fields for the command that produced it. `models`, `balance`, a newly started generation, and a waited generation do not share one guaranteed shape. Keep unknown fields, reject absent fields needed by the next step, and never fall back to scraping the help banner.

Avoid secret leakage in CI logs

Supply `OFFLINECREATOR_API_KEY` through a secret environment facility, not a command argument or echoed shell assignment. The configuration loader reads the key from the environment, and the client places it in the Authorization header rather than normal JSON output. Shell tracing can still reveal values before the process starts, so disable command echo around secret injection, redact captured error bodies as needed, and store only the non-sensitive response fields required by the next step.

When the API client raises an authenticated request error, serialize a sanitized category and HTTP status rather than the complete environment or command trace. The client applies the bearer credential in the request header; disabling shell tracing around process launch prevents the surrounding runner from leaking a value the CLI itself does not print.

Use a stable wrapper contract

Wrap the package with a small adapter that returns your own durable result: command, package version, exit code, parsed payload or diagnostic category, and timestamp. This insulates callers from formatting details while preserving the original stdout and stderr separately for debugging. The npm registry identified the current package as version 0.1.2 on the research date, so pin the version used in CI and run its own `--help` during upgrades before accepting a changed command surface.

Create fixture checks for each command your wrapper permits: valid JSON on success, stderr plus nonzero status for an invalid invocation, and no parsing of unknown-command help output. Run those checks against the pinned npm artifact before changing versions.

Related reading