From d35fff97fa399437e102f752900450ab8907c394 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Wed, 19 Aug 2026 23:51:26 +0530 Subject: [PATCH 1/2] docs(m171): one rejection shape and exit 4 for every CLI command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The published exit-code table already said `4` meant invalid command input; the client only did that for the handful of commands that validated their own flags. Now that every command agrees, the command reference stops listing invalid input under `2` — that row is network failure alone. Adds the rejection output shape, the `--json` error envelope with its stable codes, and the group-help-on-stdout behavior. Co-Authored-By: Claude Opus 5 (1M context) --- changelog.mdx | 15 +++++++++++++++ cli/agentsfleet.mdx | 25 +++++++++++++++++++++++-- cli/flags.mdx | 2 ++ 3 files changed, 40 insertions(+), 2 deletions(-) diff --git a/changelog.mdx b/changelog.mdx index f297d98..e455af7 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -7,6 +7,21 @@ description: "Stay up to date with the latest agentsfleet product updates, new f agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner. + + ## Every command answers a mistyped invocation the same way + + A missing argument used to be reported one of two ways depending on which command you ran. `agentsfleet logs` named what was missing and exited `4`; `agentsfleet events` printed a bare parser message, offered no way to fix it, and exited `2` — the same code a network failure returns, so a script could not tell a typo from an unreachable daemon. Every command now prints what is missing and the command that supplies it, and every rejected invocation exits `4`. Exit `2` means a network failure and nothing else. + + ## What's new + + - **A rejection names the fix, not just the fault.** `agentsfleet events` answers `✕ error: missing required argument 'fleet_id'` followed by `Suggestion: usage: agentsfleet events [options] `. + - **An unknown command still suggests the nearest match** and points at the command list it belongs to. + - **`--json` rejections are parseable.** A rejected invocation emits `{"error":{"code","message"}}` on standard error with a stable `code` — `MISSING_ARGUMENT`, `MISSING_OPTION_VALUE`, `MISSING_REQUIRED_OPTION`, `UNKNOWN_COMMAND`, `UNKNOWN_OPTION`, `INVALID_ARGUMENT`, or `EXCESS_ARGUMENTS`. It printed human text before. + - **A command group run bare prints help on standard output,** so `agentsfleet workspace | less` is no longer empty. It went to standard error while exiting `0`. + - **`agentsfleet logs` stops repeating itself.** Its suggestion line said the same sentence as the error above it; it now carries the runnable usage line, as `grant list` now does too. + - **The published exit-code table is what the client does.** [The command reference](/cli/agentsfleet#errors) listed `2` as covering invalid input as well as network failure; that row is now network failure alone. + + ## A hardened runner completes credentialed work again diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index e915242..c347a97 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -151,12 +151,33 @@ credential. |---|---| | `0` | The command succeeded. | | `1` | Authentication, session, or unexpected failure. | -| `2` | Network failure, rate limit, or invalid command input. | +| `2` | Network failure or rate limit. | | `3` | The API returned a server failure. | -| `4` | A supplied value failed validation. | +| `4` | The invocation was rejected: a missing argument, a missing or unrecognized flag, a value that failed validation, or an unknown command. | | `5` | Local configuration is missing or invalid. | | `130` | You interrupted the command. | +A rejected invocation is answered before any request is sent, and always in the same form: what is missing, then the command that supplies it. + +``` +$ agentsfleet events +✕ error: missing required argument 'fleet_id' + Suggestion: usage: agentsfleet events [options] +``` + +Under `--json` the same rejection is a parseable envelope on standard error, carrying a stable `code` you can switch on: + +```json +{ + "error": { + "code": "MISSING_ARGUMENT", + "message": "missing required argument 'fleet_id'" + } +} +``` + +The codes are `MISSING_ARGUMENT`, `MISSING_OPTION_VALUE`, `MISSING_REQUIRED_OPTION`, `UNKNOWN_COMMAND`, `UNKNOWN_OPTION`, `INVALID_ARGUMENT`, and `EXCESS_ARGUMENTS`. + API failures include a stable error code and request identifier when the server supplies them. Use both values when reporting a problem. ## Related pages diff --git a/cli/flags.mdx b/cli/flags.mdx index 3edfed3..c13a579 100644 --- a/cli/flags.mdx +++ b/cli/flags.mdx @@ -51,6 +51,8 @@ Invalid command input returns `4`. Local configuration failures return `5`. An interrupted browser login returns `130`. +A command group run without a subcommand prints its help on standard output and exits `0`, so `agentsfleet workspace | less` shows the same body `agentsfleet workspace --help` does. + JSON errors include the stable product error identifier when the API supplies one. See the [error registry](/api-reference/error-codes). ## Related pages From 15eabed8967bf694ca6ad669862b8bf0fbc98935 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 20 Aug 2026 00:35:07 +0530 Subject: [PATCH 2/2] docs(m171): the rejection sentence covers every rejection, not just absence Review caught the over-promise: "what is missing" describes a missing argument, but an unknown command, an unrecognized flag, a malformed value, and excess arguments all reject with nothing missing. The shape claim (detail line, then Suggestion line) does hold for all of them, so the sentence now says what is wrong rather than what is absent, and names the three kinds. Co-Authored-By: Claude Opus 5 (1M context) --- cli/agentsfleet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index c347a97..37da05e 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -157,7 +157,7 @@ credential. | `5` | Local configuration is missing or invalid. | | `130` | You interrupted the command. | -A rejected invocation is answered before any request is sent, and always in the same form: what is missing, then the command that supplies it. +A rejected invocation is answered before any request is sent. The form is always the same: what is wrong, then the command that puts it right. What is wrong may be an absent argument, a value that failed validation, or an unrecognized command. ``` $ agentsfleet events