avo-cli 4.2.0.beta.3 → 4.2.0.beta.5

data/payload/README.md

@@ -1,263 +1,65 @@
 # 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.
+It talks to any Rails app running `avo-api` over HTTP; nothing is installed in
+the app. A table per command for a person, the raw JSON body under
+`--format json` for a script or an agent.
 
-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).
+The full guide is at [docs.avohq.io/4.0/cli](https://docs.avohq.io/4.0/cli.html).
 
 ## 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
+- Ruby 3.0 or newer, for the `avo` executable.
+- Node 22 or newer on your `PATH`, or named by `AVO_CLI_NODE`. Node is not
+  bundled.
+- An app running `avo-api`, reachable over HTTP, and an
+  [API token](https://docs.avohq.io/4.0/rest-api.html#create-a-token) created
+  in that app.
 
-## Install (development)
+## Install
 
 ```sh
-cd gems/avo-cli
-yarn install
-./bin/dev.js --version
+gem install avo-cli
+avo --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
+## Connect
 
 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 login     # asks for the API base URL, the token and the API version, checks them, saves them
+avo schema    # what the token may reach
 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.
-
-The host is the API base URL: the address `avo-api` answers on, mount path
-included, exactly what you would paste into Postman before `/resources/...`.
-An app that mounts it the usual way is `http://localhost:3000/api`; one that
-mounts it elsewhere, say `mount_avo_api at: "avo"`, is
-`http://localhost:3000/avo`. The CLI appends only `/resources/<version>/<path>`
-and guesses no mount, so the address that works in a browser works here.
-
-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    | API base URL, mount path included, e.g. `http://localhost:3000/api` |
-| `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.
+The API base URL is the address `avo-api` answers on, mount path included,
+e.g. `http://localhost:3000/api`. The token is saved as plain text in
+`~/.config/avo/config.json`, so use one you can revoke.
 
-```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
-```
+For CI and scripts, skip `login` and set `AVO_API_HOST`, `AVO_API_TOKEN` and
+`AVO_API_VERSION`, or pass `--host`, `--token` and `--api-version`. See
+[Connect without logging in](https://docs.avohq.io/4.0/cli.html#connect-without-logging-in).
 
-### Grammar
+## Usage
 
 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
+avo <verb> <resource> [id] [flags]
 ```
 
-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.
+```sh
+avo schema users                        # the fields a create sends
+avo list users --sort name --dir desc   # a page of records
+avo get users 5 --format json           # one record, as the server sent it
+avo create users --data '{"name": "Ada", "email": "ada@example.com"}'
+avo update users 5 --data '{"name": "Ada King"}'
+avo delete users 5                      # no confirmation
 ```
 
-### 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.
+Field formats, errors and exit codes are in the
+[docs](https://docs.avohq.io/4.0/cli.html#send-the-right-value-for-a-field).
 
 <!-- commands -->
 * [`avo create RESOURCE`](#avo-create-resource)
@@ -293,7 +95,8 @@ CONNECTION FLAGS
 
 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
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it, indented
+                        on a terminal
                         <options: table|json>
   --verbose             Log each request and response line to stderr
 
@@ -334,7 +137,8 @@ CONNECTION FLAGS
   --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
+  --format=<option>  [default: table] Output format; `json` prints the body exactly as the server sent it, indented on a
+                     terminal
                      <options: table|json>
   --verbose          Log each request and response line to stderr
 
@@ -368,7 +172,8 @@ CONNECTION FLAGS
 
 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
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it, indented
+                        on a terminal
                         <options: table|json>
   --verbose             Log each request and response line to stderr
 
@@ -427,7 +232,8 @@ CONNECTION FLAGS
 
 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
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it, indented
+                        on a terminal
                         <options: table|json>
   --verbose             Log each request and response line to stderr
 
@@ -455,10 +261,10 @@ 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] API base URL, including the mount path, e.g. http://localhost:3000/api
-  --token=<value>        [env: AVO_API_TOKEN] API token secret, sent as a Bearer token
+  --api-version=<value>  API version segment of the URL to save; asked for when absent, Enter takes v1
+  --host=<value>         API base URL to save, including the mount path, e.g. http://localhost:3000/api; asked for when
+                         absent
+  --token=<value>        API token secret to save; asked for when absent
 
 OUTPUT FLAGS
   --verbose  Log each request and response line to stderr
@@ -478,14 +284,15 @@ EXAMPLES
 
 ## `avo logout`
 
-Delete the saved host and token. AVO_API_HOST and AVO_API_TOKEN set in the environment are not affected
+Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep working
 
 ```
 USAGE
   $ avo logout
 
 DESCRIPTION
-  Delete the saved host and token. AVO_API_HOST and AVO_API_TOKEN set in the environment are not affected
+  Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep
+  working
 
 EXAMPLES
   $ avo logout
@@ -504,8 +311,8 @@ 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)
+  --view=<value>  Which view's fields: create/update list what a write may send, with their field_options; 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,
@@ -514,7 +321,8 @@ CONNECTION FLAGS
   --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
+  --format=<option>  [default: table] Output format; `json` prints the body exactly as the server sent it, indented on a
+                     terminal
                      <options: table|json>
   --verbose          Log each request and response line to stderr
 
@@ -557,7 +365,8 @@ CONNECTION FLAGS
 
 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
+  --format=<option>     [default: table] Output format; `json` prints the body exactly as the server sent it, indented
+                        on a terminal
                         <options: table|json>
   --verbose             Log each request and response line to stderr
 
@@ -578,35 +387,3 @@ EXAMPLES
   $ 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/payload/dist/base-command.js

@@ -1,6 +1,7 @@
-import { Command, Flags } from '@oclif/core';
+import { Command, Flags, ux } from '@oclif/core';
 import { Client } from './client.js';
 import { DEFAULT_API_VERSION, resolveConfig } from './config.js';
+import { terminal } from './terminal.js';
 // The connection flags every command shares, plus a client built from them. Flag > env is oclif's job; the saved
 // file and the defaults come after, in `resolveConfig`. `login` stops here: it prints no table and no JSON.
 export class ConnectionCommand extends Command {
@@ -41,7 +42,7 @@ export class BaseCommand extends ConnectionCommand {
         ...ConnectionCommand.baseFlags,
         format: Flags.string({
             default: 'table',
-            description: 'Output format; `json` prints the body exactly as the server sent it',
+            description: 'Output format; `json` prints the body exactly as the server sent it, indented on a terminal',
             helpGroup: 'OUTPUT',
             options: ['table', 'json'],
         }),
@@ -51,10 +52,19 @@ export class BaseCommand extends ConnectionCommand {
     printedJson(flags, response) {
         if (flags.format !== 'json')
             return false;
+        const body = terminal().tty && response.body !== undefined ? indented(response.body) : response.raw;
         // `this.log` always appends a newline, which would double the one a body ends with.
-        process.stdout.write(response.raw);
-        if (!response.raw.endsWith('\n'))
+        process.stdout.write(body);
+        if (!body.endsWith('\n'))
             process.stdout.write('\n');
         return true;
     }
 }
+// `colorizeJson` colours nothing without a theme. Standard ANSI names only, so the terminal's own palette decides
+// and light and dark both work; structure (braces, colons, commas) stays in the default colour.
+const JSON_THEME = { boolean: 'magenta', key: 'cyan', null: 'dim', number: 'yellow', string: 'green' };
+// A person reads the body indented and coloured; a pipe gets the server's bytes (decisions.md section 4). A body the
+// client could not parse is printed as sent: it is still the server's answer.
+function indented(body) {
+    return ux.colorizeJson(body, { pretty: true, theme: JSON_THEME });
+}

data/payload/dist/commands/create.js

@@ -21,6 +21,6 @@ export default class Create extends WriteCommand {
         const client = this.client(flags);
         const data = await readData(flags.data);
         const response = await this.sendFields(client, { method: 'POST', view: 'create' }, [args.resource], data);
-        this.printRecord(response, flags);
+        await this.printRecord(response, flags, { resource: args.resource, verb: 'Created' });
     }
 }

data/payload/dist/commands/get.js

@@ -14,6 +14,6 @@ export default class Get extends RecordCommand {
     static hiddenAliases = ['g'];
     async run() {
         const { args, flags } = await this.parse(Get);
-        this.printRecord(await this.client(flags).get([args.resource, args.id]), flags);
+        await this.printRecord(await this.client(flags).get([args.resource, args.id]), flags);
     }
 }

data/payload/dist/commands/list.js

@@ -1,7 +1,8 @@
 import { Flags } from '@oclif/core';
 import { wrongShape } from '../errors.js';
 import { RecordCommand } from '../record-command.js';
-import { renderTable } from '../table.js';
+import { hiddenColumnsNote, layoutTable } from '../table.js';
+import { paint, terminal } from '../terminal.js';
 export default class List extends RecordCommand {
     static args = { resource: RecordCommand.resourceArg };
     static description = 'List the records of a resource, one page at a time';
@@ -33,10 +34,38 @@ export default class List extends RecordCommand {
         if (this.printedJson(flags, response))
             return;
         const { pagination, records } = parseRecords(response);
-        this.log(records.length === 0 ? `No ${args.resource} records.` : renderTable(records, flags.fields));
-        if (typeof pagination?.page === 'number') {
-            this.log(`Page ${pagination.page} of ${pagination.total_pages} (${pagination.total_count} records)`);
+        const layout = records.length === 0 ? undefined : await layoutTable(records, { columns: flags.fields });
+        this.log(layout?.text ?? `No ${args.resource}.`);
+        if (typeof pagination?.page !== 'number')
+            return;
+        const { page, total_count: count, total_pages: pages } = pagination;
+        // The server answers a page past the end with the first one; said on stderr, so the footer is not read as
+        // confirming the page that was asked for.
+        if (flags.page !== undefined && flags.page !== page) {
+            this.logToStderr(`Page ${flags.page} does not exist; showing page ${page} of ${pages}.`);
+        }
+        const footer = [`Page ${page} of ${pages} (${count} records)`];
+        const note = layout && hiddenColumnsNote(layout, ['--fields picks them']);
+        if (note)
+            footer.push(note);
+        if (typeof pages === 'number' && page < pages) {
+            footer.push(paint(terminal(), 'dim', `Next: ${this.nextPageLine(args.resource, flags, page + 1)}`));
         }
+        this.log(footer.join('. '));
+    }
+    // The same line with `--page` moved on, so it can be pasted as it stands: without the page size and the sort, the
+    // next page would be a different page.
+    nextPageLine(resource, flags, page) {
+        const words = [this.config.bin, 'list', resource, '--page', String(page)];
+        if (flags['per-page'] !== undefined)
+            words.push('--per-page', String(flags['per-page']));
+        if (flags.sort !== undefined)
+            words.push('--sort', flags.sort);
+        if (flags.dir !== undefined)
+            words.push('--dir', flags.dir);
+        if (flags.fields !== undefined)
+            words.push('--fields', flags.fields.join(','));
+        return words.join(' ');
     }
 }
 function parseRecords(response) {

data/payload/dist/commands/login.js

@@ -13,6 +13,25 @@ export default class Login extends ConnectionCommand {
         '<%= config.bin %> login --host http://localhost:3000/api --token avo_...',
         '<%= config.bin %> login --api-version v2',
     ];
+    // The connection flags again, without their `env:`. `login` is run to replace what a shell may have exported, so
+    // an export answering for it would save the very values the user came to change, and never ask.
+    static flags = {
+        'api-version': {
+            ...ConnectionCommand.baseFlags['api-version'],
+            description: `API version segment of the URL to save; asked for when absent, Enter takes ${DEFAULT_API_VERSION}`,
+            env: undefined,
+        },
+        host: {
+            ...ConnectionCommand.baseFlags.host,
+            description: 'API base URL to save, including the mount path, e.g. http://localhost:3000/api; asked for when absent',
+            env: undefined,
+        },
+        token: {
+            ...ConnectionCommand.baseFlags.token,
+            description: 'API token secret to save; asked for when absent',
+            env: undefined,
+        },
+    };
     // On stderr, like any prompt: `avo login > log` still shows the questions, and the log gets only the result.
     static prompts = {
         input: (config) => input(config, { output: process.stderr }),
@@ -30,7 +49,7 @@ export default class Login extends ConnectionCommand {
         this.log(`Saved to ${file}${replaced ? ' (replaced the previous one).' : '.'}`);
     }
     async askHost() {
-        this.requireTerminal('host', '--host', 'AVO_API_HOST');
+        this.requireTerminal('host', '--host');
         // Normalized with the rest in `resolveConfig`; the prompt has already accepted it.
         return Login.prompts.input({
             message: 'API base URL (e.g. http://localhost:3000/api):',
@@ -38,14 +57,15 @@ export default class Login extends ConnectionCommand {
         });
     }
     async askToken() {
-        this.requireTerminal('token', '--token', 'AVO_API_TOKEN');
+        this.requireTerminal('token', '--token');
         return Login.prompts.password({
             mask: true,
             message: 'API token:',
             validate: (value) => (value.length > 0 ? problemWith(checkToken)(value) : 'The token cannot be empty.'),
         });
     }
-    // The version has a default, so without a terminal it is taken rather than refused: CI gives host and token only.
+    // The version has a default, so without a terminal it is taken rather than refused: a script passes host and token
+    // only.
     async askVersion() {
         if (!Login.prompts.isTTY())
             return DEFAULT_API_VERSION;
@@ -54,8 +74,8 @@ export default class Login extends ConnectionCommand {
             message: 'API version:',
         });
     }
-    // A value given by flag or env is an answer already, so only the rest is asked for. The answers are raw, for
-    // `resolveConfig`; a bad `--host` is checked here only so it fails before the token is asked for.
+    // A value given by flag is an answer already, so only the rest is asked for; the environment is not read (see
+    // `flags`). The answers are raw, for `resolveConfig`; a bad `--host` is checked here so it fails before the token.
     async collect(flags) {
         try {
             if (flags.host)
@@ -72,10 +92,10 @@ export default class Login extends ConnectionCommand {
             throw error;
         }
     }
-    requireTerminal(what, flag, env) {
+    requireTerminal(what, flag) {
         if (Login.prompts.isTTY())
             return;
-        throw CliError.usage(`No ${what}. \`avo login\` cannot ask without a terminal; pass ${flag} or set ${env}.`);
+        throw CliError.usage(`No ${what}. \`avo login\` cannot ask without a terminal; pass ${flag}.`);
     }
 }
 // Turns the check `resolveConfig` runs into a prompt's own, so a bad answer is asked again with the reason rather

data/payload/dist/commands/logout.js

@@ -2,7 +2,7 @@ import { Command } from '@oclif/core';
 import { fileIn, remove } from '../store.js';
 // Not a `BaseCommand`: it makes no request, so the connection flags would be on `--help` doing nothing.
 export default class Logout extends Command {
-    static description = 'Delete the saved host and token. AVO_API_HOST and AVO_API_TOKEN set in the environment are not affected';
+    static description = 'Delete the saved host and token. AVO_API_HOST, AVO_API_TOKEN and AVO_API_VERSION exported in the environment keep working';
     static examples = ['<%= config.bin %> logout'];
     async run() {
         // Nothing to read from it: parsing is what refuses a flag this command does not have, instead of ignoring it.