feat: Reach every agent endpoint from the CLI

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to the FlatRun CLI are documented in this file.
 
+## [0.3.0] - 2026-08-11
+
+### Added
+
+- Every agent endpoint is now a command: `flatrun FAMILY OPERATION [ARGS]`, covering 294 endpoints across 42 families. The table is generated from the agent's routes, so catching up is a regeneration rather than 294 hand-written wrappers.
+- `flatrun` lists the families, `flatrun FAMILY` lists its commands, and `--json` on either prints the same list with each command's method, path and arguments, for scripts and agents. One listing covers both the hand-shaped commands and the generated ones, and the singular families reach everything their plural counterparts do, so `deployment log-sources` works.
+- Request bodies from repeatable `-f name=value`, or `--data JSON` / `--data @file.json`. A field value that reads as JSON is sent as JSON, so `-f enabled=true` sends a boolean. Query parameters with repeatable `-q name=value`.
+
+- Commands read the agent's own description of its API where the agent serves one, so a mistyped field or query parameter fails before the request with the name it was probably meant to be, `COMMAND --help` lists the fields an endpoint takes and the permission it needs, and answers print as tables laid out from the types the agent returns. An agent that does not describe itself behaves as before.
+
+### Fixed
+
+- `-url`, `-token` and other single-dash flags swallowed the following argument, because only the double-dash spelling was registered as taking a value.
+- Path arguments were not escaped, so a value containing a slash reshaped the request path.
+
 ## [0.2.0] - 2026-06-15
 
 ### Added

README.md

@@ -96,7 +96,44 @@ flatrun container exec abc123 -- sh -c 'printenv | sort'
 
 `deployment action` runs a quick action defined on the deployment; `deployment actions` lists them. `deployment exec` runs an ad-hoc command instead: the command follows `--`, and the service is chosen positionally or with `--service` (a single-service deployment is resolved automatically, a multi-service one must be named). Both run in the service container, honor the deployment's protected-mode rules, and surface the command's output (including on a non-zero exit).
 
-Call any backend endpoint while a polished command is still pending:
+### Every other resource
+
+The commands above are shaped by hand because they print tables worth reading. Every other agent
+endpoint is `flatrun FAMILY OPERATION [ARGS]`, from a table generated out of the agent's routes.
+
+```bash
+flatrun                       # the families
+flatrun backups               # what backups can do
+flatrun backups list
+flatrun certificates renew shop.example.com
+flatrun deployment logs my-api -q service=web -q tail=200
+```
+
+Bodies go in as fields or as JSON:
+
+```bash
+flatrun domains create -f domain=shop.example.com -f deployment=shop
+flatrun settings update --data '{"backups":{"enabled":true}}'
+flatrun settings update --data @settings.json
+```
+
+A field value that reads as JSON is sent as JSON: `-f enabled=true` sends a boolean, `-f retention=7`
+sends a number.
+
+### Driving it from a script or an agent
+
+`--json` on any listing prints every command with its method, path and arguments:
+
+```bash
+flatrun --json | jq '.[] | select(.family == "backups")'
+flatrun backups --json
+```
+
+Add `--json` to any command for the raw response.
+
+### The raw bridge
+
+For anything the table does not cover, such as a streaming endpoint:
 
 ```bash
 flatrun api get /settings

VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

docs/reference/commands.md

@@ -130,9 +130,57 @@ flatrun container restart CONTAINER_ID
 flatrun container delete CONTAINER_ID
 ```
 
+## Every other resource
+
+The families above are shaped by hand. Every other agent endpoint is
+`flatrun FAMILY OPERATION [ARGS]`, from a table generated out of the agent's routes.
+
+```bash
+flatrun                     # the families
+flatrun backups             # what backups can do
+flatrun backups list
+flatrun backups restore BACKUP_ID
+flatrun certificates renew shop.example.com
+```
+
+Operation names follow the endpoint: a collection is `list`, one item is `get`, and a sub-resource
+keeps its noun (`log-sources`, `actions`, `jobs`). Where a read and a write share a path, the read
+keeps the plain name (`log-sources`, `log-sources-update`). Where a verb applies to one item or to
+all of them, the targeted one is plain, so `certificates renew DOMAIN` renews one and
+`certificates renew-all` renews everything.
+
+### Sending a body
+
+```bash
+flatrun domains create -f domain=shop.example.com -f deployment=shop
+flatrun settings update --data '{"backups":{"enabled":true}}'
+flatrun settings update --data @settings.json
+```
+
+`-f name=value` is repeatable. A value that reads as JSON is sent as JSON, so `-f enabled=true`
+sends a boolean and `-f ports=[8080]` sends an array. The two body forms cannot be combined.
+
+### Query parameters
+
+```bash
+flatrun deployment logs my-api -q service=web -q tail=200
+```
+
+## Listing what exists
+
+```bash
+flatrun                       # the families
+flatrun backups               # one family
+flatrun --json                # every command as JSON
+flatrun backups --json        # one family as JSON
+```
+
+The JSON gives each command's family, operation, method, path, arguments and exact invocation,
+which is what a script or an agent needs to use the CLI without reading this page.
+
 ## Raw API
 
-Use the raw API bridge while a polished command is still pending:
+Use the raw API bridge for anything the table does not cover, such as a streaming endpoint:
 
 ```bash
 flatrun api get /settings