feat(tokens): add a metrics gen command to create Warp 10 read tokens

[miton18]

What

Adds clever tokens metrics gen, which mints a Warp 10 READ token through POST /v4/stats/organisations/{ownerId}/tokens/read.

$ clever tokens metrics gen
? Which organisation do you want a token for? › Rémi Collignon (personal space)
? Which applications do you want to read? › ◉ metrics  ◉ metrics.accesslogs  ◯ addon-api-cellar  ◯ addon-api-fsbucket
? Token lifespan, as an ISO 8601 duration (e.g.: P5D, PT12H) or a "1h, 4d, 2w" like duration: › P5D

✔ Metrics read token successfully created! Store it securely, you won't be able to print it again.

  - Owner        : Rémi Collignon
  - Applications : metrics, metrics.accesslogs
  - Expiration   : 2026-08-31 09:12
  - Token        : …

Why

Getting a Warp 10 token today means either the Console's Metrics tab — which only ever hands out one fixed scope — or a hand-rolled clever curl with a JSON body most people have to be told about. Neither lets you ask for, say, FS Bucket storage metrics, which is what prompted this.

Design notes

Prompts are skipped when the option is given. --org, --apps and --ttl each bypass their prompt, so the command is scriptable and CI-safe. Without a TTY the existing assertInteractiveTerminal guard fires with the option to use, rather than the silent exit(1) a raw Inquirer EOF would produce.

The application list is not validation. Which applications an owner may request is a server-side allow-list that varies per deployment, so PLATFORM_APPLICATIONS drives the checkbox and nothing else — --apps is passed through untouched. A stale list here would otherwise reject an application the platform has since opened up, and the API's own error already names what it accepts:

$ clever tokens metrics gen -o … -a bogus-app -t P1D
[ERROR] bogus-app not in expected values [metrics, addon-api-cellar, metrics.accesslogs, addon-api-fsbucket]

since: null on both definitions, per scripts/resolve-since.js — the release resolves it.

Two things worth a reviewer's eye:

• The personal space is listed twice by /v2/summary: it appears in organisations with the same id as user. A bare [user, ...organisations] (the shape models/addon.js uses, where it only costs a wasted loop iteration) renders a visible duplicate in a picker, so the choices are deduplicated on first occurrence — which also keeps the personal space at the top.
• The TTL rule lives in a superRefine on the input schema rather than only in the transform. promptTextOption validates against the unwrapped input schema, so this is what makes a typo re-ask instead of throwing the prompt away. iso8601Duration stays the single source of truth for the grammar and its message is forwarded verbatim, which is why PT0S says something useful:

$ clever tokens metrics gen … -t nope
ttl: Invalid duration: "nope", expect an ISO 8601 duration (e.g.: P5D, PT12H) or a "1h, 4d, 2w" like duration
$ clever tokens metrics gen … -t PT0S
ttl: Invalid duration: "PT0S", it must be strictly positive

src/parsers.js

New iso8601Duration: same grammar as durationInSeconds minus the bare number of seconds (ambiguous here), but returns a duration instead of a count, so P5D is sent as P5D rather than 432000 and the API echoes back something the user recognises. parseSimpleDuration now shares the short-unit conversion with it — same behaviour, one copy.

Open question for the reviewer

clever tokens' own description still reads "Manage API tokens to query Clever Cloud API from https://api-bridge.clever-cloud.com". That stays true of the bare command, which lists API tokens, but the group now also holds Warp 10 metrics tokens. I left the string alone rather than reword a released command's help as a side effect of this PR — say the word and I'll broaden it.

Verification

npm run validate clean (eslint, prettier, tsc, docs:check).

Run against the production API, not mocked:

• non-interactive with -t 5d → token expiring exactly 5 days later, so the short form normalises correctly
• non-interactive with -t 2h → 2 hours
• --org by name resolves through Organisation.getId
• full interactive flow driven over a real pty → token with the default applications
• --apps '' and --apps ' metrics , ' → the first errors client-side, the second yields ['metrics']
• no TTY and no --org → This command requires an interactive terminal. Use --org <org-id|org-name> to skip this prompt.

No unit tests: the repo has no test suite for commands, so this follows the existing convention.

Note

The branch is still named feat/metrics-gen-token, from the first naming of this command (clever metrics gen-token). GitHub can't retarget a PR's head branch, so it stays — the commit and the command are the ones that matter.

Follow-up

The FS Bucket storage metric this unblocks is documented in CleverCloud/documentation#998.

[github-actions]

🔎 A preview has been automatically published!

If you created the alias to the preview script, you can run this command to download and install this preview:

clever-preview update feat-metrics-gen-token

You can also run it from your local repository:

./scripts/preview.js update feat-metrics-gen-token

OS	SHA256 checksum
🐧 linux	d9776b8eec2a454d2170b2f8371f36a5845f2bbb893a954714794f64e24472de
🍏 macos	6f15d63ce05665548bc7f25749815bce9e67adc9cff44d846b0ceecfc3d9481f

This preview will be deleted once this PR is closed.