avo-cli 0.0.3 → 4.2.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdc9cde344da7e9b78fec834dc6669b962ec8d38dc8395e82bd7474d19443150
-  data.tar.gz: 43f5a3687bcf7b8b8522b21ebcdb920b6663ef46668cd2a46a65c5805d9c185e
+  metadata.gz: 693a493271a4046b7de64b56c79e7ca47317d53e5f3463f432b4c8f4fdea0368
+  data.tar.gz: 42d38d237c710dc2be011924039e0a00eef23b3a754736a71e21f22d6ba8642f
 SHA512:
-  metadata.gz: 6dad703e9fe4078220fd5f7e2c13c557a2409f62fba4f10b311cf39c4ac5891533884ba8d6691490b5557dfb8658fd22e3ddd0827d9117e728a98c6382208237
-  data.tar.gz: 9588be062d50b08c33680aabc4284a8976ac0425f6ba35984fc0937b714d54f839a793266a60cb1f8a3161a9284182e957a6a92f29d82d954f56f5d63a3cf64c
+  metadata.gz: 116f8ff946f36dad80ca4c996d699d6951796795c91950e009859e6a60302e45433d8b9cae7f43ff4cdafdbfea702a9defd37d648eb2d5ad3e8afbad7dc75097
+  data.tar.gz: c2224fe2ba6074f14270e0bcee03d9129e308b111da3435c6d9607be9276117087025a22eaf9ac4e9eab414903aeeb45921f946f7ddb9c201099358a79c5a065

data/README.md

@@ -0,0 +1,605 @@
+# avo-cli
+
+Command line client for the [Avo REST API](https://docs.avohq.io/4.0/rest-api.html).
+It talks to any Rails app running `avo-api`; nothing is installed in the app.
+
+Status: every command works against any app running `avo-api`, and the docs
+site describes them. It ships as a Ruby gem that runs the built client on the
+machine's Node ([docs/install.md](docs/install.md)); the gem builds and installs
+locally and has not been released yet. What is left is in
+[docs/plans/v1-todo.md](docs/plans/v1-todo.md).
+
+## Requirements
+
+- Running the CLI: Node 18.12.1 or newer. 18.0 fails at startup on a missing
+  `node:fs/promises` export. The installed gem also needs Ruby 3.0 or newer,
+  for the `avo` executable that finds Node and hands the line over.
+- Developing it: Node 22.13 or newer (`.node-version` pins it). The lint toolchain
+  (`@typescript-eslint` → `eslint-visitor-keys@5`) refuses anything older.
+- yarn
+
+## Install (development)
+
+```sh
+cd gems/avo-cli
+yarn install
+./bin/dev.js --version
+```
+
+`./bin/dev.js` runs the TypeScript sources directly through tsx.
+`./bin/run.js` runs the compiled `dist/` after `yarn build`. The installed gem's
+`avo` runs that same `run.js`, from the `payload/` the gem carries. To build the
+gem and install it locally, see [docs/distribution.md](docs/distribution.md) §6.
+
+## Configuration
+
+Log in once and every later command knows the app:
+
+```sh
+avo login     # asks for the host, the token and the API version (Enter for v1), checks them, saves them
+avo schema    # works in any terminal from here on
+avo logout    # deletes what was saved
+```
+
+`avo login` saves to `~/.config/avo/config.json` (`$XDG_CONFIG_HOME/avo` when
+set, `%LOCALAPPDATA%\avo` on Windows), readable by your user only. The token is
+stored as plain text, like `~/.bundle/config`, so use a token you can revoke.
+
+For CI and scripts, skip `login` and set the variables. A flag wins over its
+variable, and either wins over what was saved. The saved host and token are
+used only together: name a host or a token yourself and the saved pair is left
+out, so a saved token never reaches another host. The saved API version goes
+with them: `avo login --api-version v2` once, and later commands use `v2`.
+
+| Variable          | Flag            | Default | Purpose                                            |
+| ----------------- | --------------- | ------- | -------------------------------------------------- |
+| `AVO_API_HOST`    | `--host`        | none    | Base URL of the app, e.g. `http://localhost:3000`  |
+| `AVO_API_TOKEN`   | `--token`       | none    | API token secret, sent as `Authorization: Bearer`  |
+| `AVO_API_VERSION` | `--api-version` | `v1`    | API version segment of the URL, saved by `login`   |
+
+## Commands
+
+The gem is not released yet, so there is no `avo` on anyone's PATH: every
+example here runs the source through `./bin/dev.js`. The generated reference
+further down prints `avo`, the released name. These examples are swept to it
+when the gem ships.
+
+```sh
+./bin/dev.js schema                              # what the token may reach, as a table
+./bin/dev.js schema --format json                # the _schema body, byte for byte
+./bin/dev.js schema users                        # the fields a create sends, with required
+./bin/dev.js schema users --view show            # the fields a record reads back
+./bin/dev.js list users                          # first page, one row per record
+./bin/dev.js list users --page 2 --per-page 10   # paging
+./bin/dev.js list users --sort name --dir desc   # sorting, server side
+./bin/dev.js list users --fields id,name,email   # pick the columns
+./bin/dev.js get users 5                         # one record, field by field
+./bin/dev.js get users 5 --format json           # the body, byte for byte
+./bin/dev.js get users 5 --verbose               # request and response lines on stderr
+./bin/dev.js create users --data '{"name": "Ada", "email": "ada@example.com"}'
+./bin/dev.js update users 5 --data '{"name": "Ada King", "bio": null}'  # null clears
+./bin/dev.js create users --data @user.json      # the object from a file
+./bin/dev.js update users 5 --data - < user.json # the object from stdin
+./bin/dev.js delete users 5                      # no confirmation, see below
+./bin/dev.js login                               # save the host, token and API version
+./bin/dev.js logout                              # delete what login saved
+```
+
+### Grammar
+
+Every line has the same shape:
+
+```
+./bin/dev.js <verb> <resource> [id] [flags]
+```
+
+There are six verbs: `schema`, `list`, `get`, `create`, `update` and `delete`.
+The resource is always an argument, never a command, because route keys come
+from the app being talked to and only after an HTTP call. `login` and `logout`
+are the two commands outside the grammar: they take no resource
+([Configuration](#configuration)).
+
+`./bin/dev.js --help` lists the six verbs, with `login`, `logout` and `help`
+beside them, and `./bin/dev.js get --help` shows one. A line that names no
+command prints the usage above, with a did-you-mean when the typo is close to
+something real.
+
+Each verb has a one-letter shortcut — `s l g c u d`, in the order listed above
+— in the same slot, so `./bin/dev.js l users` is `list users`. They are hidden
+aliases: help, the reference below and the error messages all keep to the full
+spelling, and nothing else about the grammar bends. `./bin/dev.js users l` is
+refused like any other line that puts the resource first.
+
+### Output
+
+A table is plain text, two spaces between columns. `--fields` picks the
+columns and lays a table out in the flag's order; a single `get` reads down
+the page in the record's own order. A cell is one line: `-` for null and
+empty, a list joined with `, `, an object — an association included — as its
+JSON, and anything past 40 characters cut with `…`.
+
+`--format json` prints the body exactly as the server sent it and ignores
+`--fields`; `table` is the default. `--verbose` logs each request and
+response line to stderr, so `--format json --verbose | jq` still works.
+
+### Writing fields
+
+Fields are one JSON object, given through `--data` (`-d`): the JSON itself,
+`@path` to read it from a file, or `-` to read stdin. Every key is a field as
+`schema <resource>` lists them. JSON carries its own types, so nothing is
+converted — a value is sent as written. Before sending, the CLI reads the
+resource's form view: for the key the body nests under, for the `file` refusal
+below, and for the two values the wire wants in another form. What each field
+takes:
+
+| The view says                                     | You write                                       | Sent                                    |
+| ------------------------------------------------- | ----------------------------------------------- | --------------------------------------- |
+| `shape: array`                                    | `"roles": ["editor", "reviewer"]`               | as written; `null` sends `[]`           |
+| `shape: hash`, `keys: [latitude, longitude]`      | `"coordinates": {"latitude": 44.4, …}`          | as written; `null` sends every key null |
+| polymorphic `belongs_to`, two scalars             | `"reactable_type": "Post", "reactable_id": 7`   | as written                              |
+| `type: key_value` or `type: code`                 | `"settings": {"theme": "dark"}`                 | the object as a JSON string             |
+| `type: tags`                                      | `"skills": "ruby,rails"`                        | the string; the field splits it         |
+| anything else                                     | `"active": false`, `"birth_date": "1985-03-04"` | as written; the app casts               |
+
+Refused with exit `2`, before any request: `--data` that is not valid JSON or
+not one object, and an `@path` that cannot be read. Refused once the view is
+read, before the write: a `file` or `files` field, which needs a multipart
+upload the CLI does not send. Nothing else is checked against the view: the API
+validates a write, so an empty object, a field the view does not list or a
+value outside a field's `options` goes out as written and the server answers.
+An empty object is a `400`. A value outside a field's `options` is written as
+given, or a `500` where a Rails enum raises on it, and a misspelled field name
+or a value of the wrong shape is mostly dropped by the app's strong params
+without a word — the write exits `0` with that field unchanged — until
+[AVO-1804](https://linear.app/avo-hq/issue/AVO-1804) makes the API answer those
+too. Read the record back when it matters.
+[docs/field-types.md](docs/field-types.md) is the full table, type by type.
+
+Quote the object in single quotes: the shell reads the line first, and an
+unquoted `{"a":1,"b":2}` is a brace expansion that silently splits in two.
+When the quoting gets in the way — a value holding a quote, or an object too
+long for one line — write the JSON to a file and pass `--data @user.json`, or
+pipe it in with `--data -`.
+
+A `code` field takes its JSON as a string. Whether the field parses that string
+on the way in is a write transform the view does not publish — it describes the
+value a write sends, not what the field does with it afterwards — so over a
+JSON column the string lands double-encoded unless the resource declares
+`pretty_generated: true`. Setting such a field replaces the whole column;
+nothing is merged.
+
+`schema users` lists the fields a create may send, each with every key the
+view publishes for it: its `type`, whether it is `required`, its `shape`, and
+`options` or `keys` where it has them. `--view update` does the same for an
+update, and `--view index` or `--view show` list what a record comes back
+with, as `id` and `type`. The views are named by the API action they describe,
+the same words `schema` shows under `entitlements`. The answer is always for
+one view, never a merge of several, and each view needs the entitlement of the
+request it describes: a read-only token gets `index` and `show`, and on
+`create` and `update` a `403` the CLI relays like any other. A view the API
+does not serve is refused by the API, which names the ones it has. A
+`belongs_to` is listed by the key the body sets it through, `team_id`.
+
+`delete` has no body, so it reads no view and sends straight away. The server
+answers every request, and a refusal comes back as a `403` whose `reason` says
+which side to widen, `token_entitlement` or `policy`. The CLI names the request
+it made and relays the reason as it came:
+
+```
+ ›   Error: Forbidden: DELETE /api/resources/v1/users/5 was refused (reason: token_entitlement).
+```
+
+`delete` asks for no confirmation: an agent or a CI job has no terminal to
+answer a prompt on, and the line already names the record. A confirmation
+step is parked for after v1.
+
+### Errors
+
+Every error is one sentence naming what to change, on stderr. A `404` is the
+one message whatever the cause — a mistyped resource, a missing id, an app
+without `avo-api` mounted or licensed — because the API does not yet say which,
+and the CLI does not guess. `schema` lists the names this token may reach:
+
+```
+ ›   Error: Not found: http://localhost:3030/api/resources/v1/user.
+ ›   Check the resource name and the API version, and that the app has avo-api mounted and licensed.
+```
+
+A line that names no command is answered with the one grammar there is, and a
+correction above it when the typo is close to something real:
+
+```
+ ›   Error: command lst users not found
+ ›   Did you mean: avo list?
+ ›   Usage: avo <verb> <resource> [id] [flags]
+```
+
+A `422` lists what the app refused, one line per field:
+
+```
+ ›   Error: Failed to create User
+ ›     name: can't be blank
+ ›     email: has already been taken
+```
+
+A wrong secret, an expired token and a revoked one all read the same
+`Unauthorized`: the server does not say which, since saying would confirm a
+guessed secret.
+
+A redirect is reported and never followed, since the token would not survive
+it. It is usually `http://` on an app that forces `https://`:
+
+```
+ ›   Error: http://app.example.com redirected to https://app.example.com/api/resources/v1/_schema. Use the address it points to as the host.
+```
+
+### Exit codes
+
+| Code  | Meaning                                                                                      |
+| ----- | -------------------------------------------------------------------------------------------- |
+| `0`   | Success                                                                                      |
+| `1`   | The request failed: refused (400, 401, 403, 404, 422, 5xx), redirected, unreachable, timeout |
+| `2`   | Usage: the line or the setup was wrong, and nothing was written                              |
+| `130` | Interrupted: Ctrl-C at an `avo login` prompt, with nothing saved                             |
+
+Exit `1` also covers an answer that is not avo-api's: a `200` without the
+`records`, `record` or schema the endpoint promises. Exit `2` is an unknown
+command, a bad flag, `--view` with no resource, an empty id, a missing host or
+token, a host without `http://` or `https://` or with a username and password
+in it, a token holding a character a header cannot carry, `--data` that is not
+one JSON object or names a file that cannot be read, and a `file` field. It is
+also a saved login that cannot be read, written or parsed, `avo login` with a
+value left to ask for and no terminal to ask on, and the installed gem finding
+no Node, or one older than 18.12.1.
+
+<!-- commands -->
+* [`avo create RESOURCE`](#avo-create-resource)
+* [`avo delete RESOURCE ID`](#avo-delete-resource-id)
+* [`avo get RESOURCE ID`](#avo-get-resource-id)
+* [`avo help [COMMAND]`](#avo-help-command)
+* [`avo list RESOURCE`](#avo-list-resource)
+* [`avo login`](#avo-login)
+* [`avo logout`](#avo-logout)
+* [`avo schema [RESOURCE]`](#avo-schema-resource)
+* [`avo update RESOURCE ID`](#avo-update-resource-id)
+
+## `avo create RESOURCE`
+
+Create a record from one JSON object of fields
+
+```
+USAGE
+  $ avo create RESOURCE -d json|@path|- [--api-version <value>] [--host <value>] [--token <value>]
+    [--verbose] [--format table|json] [--fields field,field]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+
+FLAGS
+  -d, --data=json|@path|-  (required) Fields to write, as one JSON object; @path reads it from a file, - from stdin
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] Base URL of the app, e.g. http://localhost:3000
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --fields=field,field  Columns to show, comma-separated, e.g. id,name,email
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it
+                        <options: table|json>
+  --verbose             Log each request and response line to stderr
+
+DESCRIPTION
+  Create a record from one JSON object of fields
+
+EXAMPLES
+  $ avo create users --data '{"name": "Ada Lovelace", "email": "ada@example.com"}'
+
+  $ avo create users --data '{"name": "Ada", "active": true, "roles": ["editor", "reviewer"]}'
+
+  $ avo create comments --data '{"body": "Hi", "commentable_type": "Post", "commentable_id": 7}'
+
+  $ avo create users --data @user.json
+
+  $ avo create users --data - < user.json
+
+  $ avo create users --data '{"name": "Ada"}' --format json
+```
+
+## `avo delete RESOURCE ID`
+
+Delete a record
+
+```
+USAGE
+  $ avo delete RESOURCE ID [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
+    table|json]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+  ID        Record id
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] Base URL of the app, e.g. http://localhost:3000
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --format=<option>  [default: table] Output format; `json` prints the body exactly as the server sent it
+                     <options: table|json>
+  --verbose          Log each request and response line to stderr
+
+DESCRIPTION
+  Delete a record
+
+EXAMPLES
+  $ avo delete users 5
+
+  $ avo delete users 5 --format json
+```
+
+## `avo get RESOURCE ID`
+
+Show one record
+
+```
+USAGE
+  $ avo get RESOURCE ID [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
+    table|json] [--fields field,field]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+  ID        Record id
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] Base URL of the app, e.g. http://localhost:3000
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --fields=field,field  Columns to show, comma-separated, e.g. id,name,email
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it
+                        <options: table|json>
+  --verbose             Log each request and response line to stderr
+
+DESCRIPTION
+  Show one record
+
+EXAMPLES
+  $ avo get users 5
+
+  $ avo get users 5 --fields name,email
+
+  $ avo get users 5 --format json
+```
+
+## `avo help [COMMAND]`
+
+Display help for avo.
+
+```
+USAGE
+  $ avo help [COMMAND...] [-n]
+
+ARGUMENTS
+  [COMMAND...]  Command to show help for.
+
+FLAGS
+  -n, --nested-commands  Include all nested commands in the output.
+
+DESCRIPTION
+  Display help for avo.
+```
+
+## `avo list RESOURCE`
+
+List the records of a resource, one page at a time
+
+```
+USAGE
+  $ avo list RESOURCE [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
+    table|json] [--dir <value> --sort <value>] [--fields field,field] [--page <value>] [--per-page <value>]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+
+FLAGS
+  --dir=<value>       Sort direction: asc or desc
+  --page=<value>      Page number, starting at 1
+  --per-page=<value>  Records per page (default: the app's Avo setting)
+  --sort=<value>      Field to sort by
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] Base URL of the app, e.g. http://localhost:3000
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --fields=field,field  Columns to show, comma-separated, e.g. id,name,email
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it
+                        <options: table|json>
+  --verbose             Log each request and response line to stderr
+
+DESCRIPTION
+  List the records of a resource, one page at a time
+
+EXAMPLES
+  $ avo list users
+
+  $ avo list users --page 2 --per-page 10
+
+  $ avo list users --sort name --dir desc
+
+  $ avo list users --fields id,name,email
+
+  $ avo list users --format json
+```
+
+## `avo login`
+
+Save a host, an API token and the API version, so later commands need none of them
+
+```
+USAGE
+  $ avo login [--api-version <value>] [--host <value>] [--token <value>] [--verbose]
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] Base URL of the app, e.g. http://localhost:3000
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --verbose  Log each request and response line to stderr
+
+DESCRIPTION
+  Save a host, an API token and the API version, so later commands need none of them
+
+EXAMPLES
+  $ avo login
+
+  $ avo login --host http://localhost:3000
+
+  $ avo login --host http://localhost:3000 --token avo_...
+
+  $ avo login --api-version v2
+```
+
+## `avo logout`
+
+Delete the saved host and token. AVO_API_HOST and AVO_API_TOKEN set in the environment are not affected
+
+```
+USAGE
+  $ avo logout
+
+DESCRIPTION
+  Delete the saved host and token. AVO_API_HOST and AVO_API_TOKEN set in the environment are not affected
+
+EXAMPLES
+  $ avo logout
+```
+
+## `avo schema [RESOURCE]`
+
+List the resources the API serves, or the fields of one resource on one view
+
+```
+USAGE
+  $ avo schema [RESOURCE] [--api-version <value>] [--host <value>] [--token <value>] [--verbose] [--format
+    table|json] [--view <value>]
+
+ARGUMENTS
+  [RESOURCE]  A resource by its route key; with none, the resources the API serves are listed
+
+FLAGS
+  --view=<value>  Which view's fields: create/update list what a write may send, with required; index/show what a record
+                  reads back (default: create)
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] Base URL of the app, e.g. http://localhost:3000
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --format=<option>  [default: table] Output format; `json` prints the body exactly as the server sent it
+                     <options: table|json>
+  --verbose          Log each request and response line to stderr
+
+DESCRIPTION
+  List the resources the API serves, or the fields of one resource on one view
+
+EXAMPLES
+  $ avo schema
+
+  $ avo schema --format json
+
+  $ avo schema users
+
+  $ avo schema users --view show
+
+  $ avo schema --host http://localhost:3000 --token avo_...
+```
+
+## `avo update RESOURCE ID`
+
+Update a record from one JSON object of fields; every field not given is left as it is
+
+```
+USAGE
+  $ avo update RESOURCE ID -d json|@path|- [--api-version <value>] [--host <value>] [--token <value>]
+    [--verbose] [--format table|json] [--fields field,field]
+
+ARGUMENTS
+  RESOURCE  A resource by its route key, as `schema` lists them
+  ID        Record id
+
+FLAGS
+  -d, --data=json|@path|-  (required) Fields to write, as one JSON object; @path reads it from a file, - from stdin
+
+CONNECTION FLAGS
+  --api-version=<value>  [env: AVO_API_VERSION] API version segment of the URL; defaults to the one `avo login` saved,
+                         then v1
+  --host=<value>         [env: AVO_API_HOST] Base URL of the app, e.g. http://localhost:3000
+  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+
+OUTPUT FLAGS
+  --fields=field,field  Columns to show, comma-separated, e.g. id,name,email
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it
+                        <options: table|json>
+  --verbose             Log each request and response line to stderr
+
+DESCRIPTION
+  Update a record from one JSON object of fields; every field not given is left as it is
+
+EXAMPLES
+  $ avo update users 5 --data '{"name": "Ada King"}'
+
+  $ avo update users 5 --data '{"active": false, "age": 36}'
+
+  $ avo update users 5 --data '{"bio": null, "roles": []}'
+
+  $ avo update users 5 --data @user.json
+
+  $ avo update users 5 --data - < user.json
+
+  $ avo update users 5 --data '{"name": "Ada"}' --format json
+```
+<!-- commandsstop -->
+
+## Development
+
+```sh
+cd gems/avo-cli
+node --version   # 22.13 or newer, per `.node-version`
+
+yarn build       # compile src/ to dist/
+yarn test        # mocha, then typecheck and eslint (posttest)
+yarn typecheck   # tsc over src/ and test/, writing nothing
+yarn lint
+```
+
+Narrower runs, when the whole suite is more than you need:
+
+```sh
+yarn mocha test/commands/list.test.ts          # one file
+yarn mocha "test/**/*.test.ts" --grep "404"    # every test whose name matches
+```
+
+Tests never reach the network: HTTP is stubbed with undici's `MockAgent`,
+which Node's built-in `fetch` honours (see `test/http.test.ts`).
+
+The command reference above is generated by `oclif readme` and regenerated on
+`yarn version` and on pack. After changing a command's description, flags or
+examples, run `yarn build && yarn oclif readme --no-source-links` and commit
+the result. The flag matters: without it the reference links into the private
+workspace repository, which `test/readme.test.ts` refuses.
+
+To run the CLI against a real app, command by command, with the expected
+output and every way a line can fail, follow
+[docs/manual-testing.md](docs/manual-testing.md).

data/avo-cli.gemspec

@@ -1,28 +1,27 @@
-require_relative "lib/avo_cli/version"
+require_relative "lib/avo/cli/version"
 
 Gem::Specification.new do |spec|
-  spec.name        = "avo-cli"
-  spec.version     = AvoCli::VERSION
-  spec.summary     = "CLI to help with common tasks for Avo CMS such as linting."
-  spec.description = "CLI to help with common tasks for Avo CMS such as linting."
-  spec.authors     = ["Adrian Marin"]
-  spec.email       = "adrian@adrianthedev.com"
-  spec.files       = Dir["{bin,lib}/**/*", "LICENSE.MD", "readme.md", "avo-cli.gemspec", "Gemfile", "Gemfile.lock", "linter.png"]
-  spec.homepage    = "https://avohq.io"
-  spec.license     = "MIT"
+  spec.name = "avo-cli"
+  spec.version = Avo::Cli::VERSION
+  spec.authors = ["Avo"]
+  spec.email = ["avo@avohq.io"]
+  spec.homepage = "https://github.com/avo-hq/avo"
+  spec.summary = "Command line client for the Avo REST API"
+  spec.description = "Command line client for the Avo REST API"
+  spec.license = "Commercial"
 
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
-  if spec.respond_to?(:metadata)
-    spec.metadata["bug_tracker_uri"] = "https://github.com/avo-hq/avo-cli/issues"
-    spec.metadata["changelog_uri"] = "https://github.com/avo-hq/avo-cli/releases"
-    spec.metadata["documentation_uri"] = "https://github.com/avo-hq/avo-cli"
-    spec.metadata["homepage_uri"] = "https://avohq.io"
-    spec.metadata["source_code_uri"] = "https://github.com/avo-hq/avo-cli"
-  else
-    raise "RubyGems 2.0 or newer is required to protect against " \
-    "public gem pushes."
-  end
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  spec.required_ruby_version = ">= 3.0"
 
-  spec.executables << "avo"
+  spec.bindir = "exe"
+  spec.executables = ["avo"]
+
+  # payload/ is gitignored and picked up from disk at pack time. Run bin/build_payload before packing: the release path
+  # does not yet run it, see docs/distribution.md.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir["{exe,lib,payload}/**/*", "README.md", "avo-cli.gemspec"]
+      .reject { |f| File.symlink?(File.expand_path(f)) }
+  end
 end

data/exe/avo

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/avo/cli/runner"
+
+Avo::Cli::Runner.exec(ARGV)