Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
When a coding agent calls your CLI, its errors are part of the interface the agent must use to decide what happened and what to do next. Give failures stable machine-readable codes, consistent structured output, explicit retry and side-effect semantics, and a documented meaning for the process exit code. Keep human-readable messages useful, but never make an agent infer the failure type or retry safety by parsing prose.
What an agent-facing error contract must tell callers
A person can interpret a vague message such as “operation failed.” An agent needs enough structured information to select a safe next step. For every command outcome, define:
- What condition occurred: a stable, specific error code.
- What the caller may do: an actionable recovery hint, if one is known.
- Whether an identical retry is safe: make retryability explicit rather than implied by the wording.
- What may already have changed: state whether side effects occurred, including partial completion.
- Where to find the result: a predictable payload shape and clearly defined exit status.
OpenAI’s Agents API error guidance puts the division plainly: “For structured errors, use error.code in application logic and error.message to explain the failure.” In practice, codes should identify conditions; messages should help people understand them. A code that changes when wording changes is not a stable contract.
Free tools Windows power users keep installed
One-click scans. No signup required.
Use stable codes and a predictable response shape
Make codes the branching interface
Choose codes that distinguish conditions requiring different actions. For example, an invalid argument may call for correcting the invocation, while a temporary service failure may permit a retry under defined conditions. Avoid making callers branch on message fragments: text can be edited, localized, or augmented without changing the underlying failure.
#1 Best Overall
Document the known codes and define how consumers should handle codes they do not recognize. OpenAI’s error guidance also calls for defensive handling when an expected parameter is missing, so an unfamiliar or incomplete error must not cause the error handler itself to fail.
Keep the envelope invariant
Return errors in a consistent structure, including stable field presence across success and failure where practical. A caller should not need a separate parser for each command or failure type. The CLI Agent Spec project describes an invariant response envelope: stable error codes are for machine decisions, while messages are for people. Its ResponseEnvelope schema is one concrete example of expressing that shape.
Choose field names and types deliberately, then version or evolve the contract in a way that does not silently change existing meanings. If a value may be absent, specify whether the field is omitted, null, or represented another way; consumers should not have to guess.
Rank #2
Define retryability together with side effects
“Retryable” must answer a precise question: may the caller repeat the identical invocation unchanged and expect a safe attempt? It should not merely mean that another attempt might eventually work.
The CLI Agent Spec’s ExitCode schema defines a retryable result as one where the identical invocation may be retried unchanged and guarantees that no side effects occurred. It treats partial failure as non-retryable. That pairing matters: if a command might have created a resource, sent a message, or changed a file before failing, blind repetition could duplicate or compound the action.
Represent uncertain or partial outcomes honestly
A timeout or lost connection does not prove the command did nothing. OpenAI’s error guidance advises checking completed actions and effects before resubmitting after a failed turn. When your CLI cannot establish whether an operation took effect, do not report a guarantee of no side effects or label an identical retry safe. Return a distinct, documented outcome that directs the caller to inspect state or reconcile before proceeding.
Rank #3
Where operations support idempotency keys or status checks, document how callers use them. If they do not, state that limitation rather than inviting automatic retries based on a generic failure message.
Separate process success from task success when the contract needs both
An exit code and a structured task result can describe different layers. The process status can say whether the CLI successfully performed its own work—such as sending a request and returning a parseable response—while a payload field reports whether the requested remote task succeeded.
The A2A CLI specification uses this distinction: the process exit code reports whether the CLI did its job, while the returned task state carries the task outcome. A task can therefore fail even when the CLI successfully conducted and reported the interaction. The specification summarizes its purpose this way: “The exit code is the coarse signal for shells and CI, the only result a caller gets without parsing output.”
This is one documented contract choice, not a universal rule. A CLI may instead return nonzero whenever the requested task fails. Either approach can work if it is consistent, documented, and unambiguous about what the status means. If process success and task success differ, ensure automation can inspect both without mistaking one for the other.
Keep machine output parseable and diagnostics separate
In machine-readable mode, stdout should contain only the structured payload the caller expects. Prompts, progress indicators, logs, and diagnostics belong on stderr. Otherwise, a single human-oriented status line can corrupt JSON parsing or force consumers to strip terminal decoration before they can read the result.
The A2A CLI specification documents this stdout/stderr separation and structured JSON or JSONL output. If your CLI streams results, define the record shape and ordering, including how errors appear and whether partial output may precede a failure. Do not leave consumers to infer whether a truncated stream is a complete result.
Best Value
Make the contract discoverable
Agents and the people integrating them benefit when commands, flags, types, examples, and failure meanings can be inspected in a machine-readable form. The CLI Agent Spec describes a command manifest with these details, including exit-code maps. A manifest or schema does not replace good error behavior, but it can help a caller construct valid invocations and interpret outcomes without scraping help text.
Document both command-level errors—such as malformed arguments—and failures reported by a remote service or task. If they have different semantics, use distinct codes or namespaces and make the distinction visible in the payload.
A practical design checklist
- Assign each materially different failure a stable code, and document unknown-code handling.
- Keep human-readable messages separate from machine decisions.
- Return a predictable envelope with defined field presence and types.
- State whether an identical invocation is safe to retry and whether any side effects occurred.
- Treat partial completion and uncertain outcomes as unsafe for blind retry.
- Document whether a nonzero process status means CLI execution failed, the requested task failed, or both.
- In machine mode, reserve stdout for structured output and send diagnostics to stderr.
- Publish command and failure metadata in discoverable schemas or manifests when useful.
The CLI Agent Spec project reports 75 documented failure modes and 160 requirements in its repository state accessed on October 7, 2026. It also claims that no existing CLI framework covers more than 59% of the failure modes it currently maps. These are project-reported, mutable figures—not independently validated industry statistics. The project describes six canonical JSON schemas and a matrix of 12 frameworks over 71 mapped failure modes; those scope counts are also its own reported figures.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
