document one CLI rejection shape and exit 4

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.
 </Tip>
 
+<Update label="Aug 19, 2026" tags={["What's new"]}>
+  ## 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] <fleet_id>`.
+  - **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.
+</Update>
+
 <Update label="Aug 19, 2026" tags={["What's new", "Bug fixes"]}>
   ## A hardened runner completes credentialed work again
 

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. 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
+✕ error: missing required argument 'fleet_id'
+  Suggestion: usage: agentsfleet events [options] <fleet_id>
+```
+
+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

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