@apex-actions/cli 0.69.0 → 0.70.0

package/README.md

@@ -14,9 +14,13 @@ Part of the [Apex Actions](../) superproject. Conventions, architecture, and age
 | `apex logs` | the control-plane REST API | the operator token (`APEX_ADMIN_TOKEN`) |
 | `apex dispatch` | the control-plane REST API | the operator token (`APEX_ADMIN_TOKEN`) |
 | `apex login` · `logout` · `whoami` | the browser and the control-plane REST API | nothing — `login` mints the credential |
+| `apex token create` | the browser and the control-plane REST API | a person signed in to the dashboard, who approves it |
+| `apex token list` · `revoke` | the control-plane REST API | a customer token (`APEX_TOKEN` or `apex login`) |
 | `apex secret` · `apex variable` | the control-plane REST API | a customer token (`APEX_TOKEN` or `apex login`), repository admin |
 
-Generated reference: `docs/feature-docs/cli-commands.md` (`pnpm docs:cli`).
+Generated reference: `docs/feature-docs/cli-commands.md` (`pnpm docs:cli` from `packages/release`), and
+the structured one the public site renders, `docs/feature-docs/cli-reference.json` (`pnpm docs:reference`;
+customer commands only, classified in `cli/reference.ts`).
 
 ```bash
 export APEX_API_URL=https://apex.example
@@ -53,8 +57,9 @@ The CLI resolves one credential, in this order (control-plane ADR-0064):
 only ever sent to the control plane that issued it. `apex login` opens the consent page on the web
 app — `APEX_WEB_URL`, or the API's origin — and listens on `127.0.0.1` for the loopback callback
 (RFC 8252, PKCE). A customer token's scope is repository secrets and variables plus `/me`; every
-other command answers with the server's 403. `apex logout` deletes the file only: a token cannot
-revoke itself, so revoke it on the dashboard. No command prints a token.
+other command answers with the server's 403. `apex logout` revokes the saved token on the server,
+then deletes the file. No command prints a token — except `apex token create`, whose whole job is to
+print the new one, once.
 
 ```bash
 apex login                                                   # once per machine
@@ -64,6 +69,15 @@ apex variable set AWS_REGION --value eu-west-1 --repo acme/api
 apex secret list --repo acme/api --json                      # names only
 ```
 
+A pipeline gets its own token. It is approved in the browser like a login, printed once to stdout,
+and never saved (control-plane ADR-0064: a token never mints a token):
+
+```bash
+apex token create ci-deploy --repo acme/api --expires-in-days 30   # token on stdout, details on stderr
+apex token list                                                    # * marks the one this CLI uses
+apex token revoke 0b6f1c2e-9d4a-4f7e-8a31-5c2d9e7b1a40              # or --all
+```
+
 `apex secret set` never takes the value from the command line — argv is visible in `ps` and saved in
 shell history (BUG-0157) — so `--value` is refused with exit 2. Exit codes: 0 done · 1 the API
 refused · 2 usage or configuration · 3 not found on `delete`.

package/dist/cli/approval/main.js

@@ -70,7 +70,7 @@ const decide = (verb) => new Command(verb)
     }
 });
 export default new Command('approval')
-    .description('Runs from forks: what is waiting, and deciding it (ADR-0024)')
+    .description('Runs from forks: what is waiting for approval, and deciding it')
     .addCommand(listCommand)
     .addCommand(decide('approve'))
     .addCommand(decide('reject'));

package/dist/cli/logs/main.js

@@ -122,7 +122,11 @@ const deleteCommand = new Command('delete')
     .description('Delete every job’s log for a finished run — for everyone, and not undoable')
     .argument('<run>', 'run id, #number, or "latest" — required, never assumed')
     .option('--repo <owner/repo>', 'limit the run search to one repository')
-    .action(async (run, options) => {
+    .action(async (run, _options, command) => {
+    // `logs` declares `--repo` too, and Commander gives a shared option to the
+    // parent — so this subcommand's own options never hold it, and a #number was
+    // searched for across every repository (found live on 0.69.0). Read both.
+    const options = command.optsWithGlobals();
     const repository = options.repo === undefined ? undefined : parseRepository(options.repo);
     if (options.repo !== undefined && repository === undefined) {
         console.error(chalk.red(`--repo must be owner/repo, got ${options.repo}`));

package/dist/cli/main.js

@@ -1,37 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { Command } from 'commander';
-import Run from './run/main.js';
-import Validate from './validate/main.js';
-import Migrate from './migrate/main.js';
-import Logs from './logs/main.js';
-import Search from './search/main.js';
-import Why from './why/main.js';
-import Reproduce from './reproduce/main.js';
-import Timing from './timing/main.js';
-import Tests from './tests/main.js';
-import Rerun from './rerun/main.js';
-import Spend from './spend/main.js';
-import Dispatch from './dispatch/main.js';
-import Runner from './runner/main.js';
-import Cache from './cache/main.js';
-import Artifact from './artifact/main.js';
-import Environment from './environment/main.js';
-import Deployment from './deployment/main.js';
-import Approval from './approval/main.js';
-import Schedule from './schedule/main.js';
-import Oidc from './oidc/main.js';
-import Actions from './actions/main.js';
-import Terms from './terms/main.js';
-import Tenant from './tenant/main.js';
-import Notify from './notify/main.js';
-import Lsp from './lsp/main.js';
-import Login from './login/main.js';
-import Logout from './logout/main.js';
-import Whoami from './whoami/main.js';
-import Secret from './secret/main.js';
-import Variable from './variable/main.js';
+import { buildProgram } from './program.js';
 /**
  * The version, from the nearest `package.json` rather than from `VERSION`.
  *
@@ -52,39 +22,4 @@ const readVersion = () => {
         }
     }
 };
-const version = readVersion();
-const program = new Command()
-    .name('apex')
-    .description('Apex Actions — developer and operator CLI')
-    .version(version)
-    .addCommand(Run)
-    .addCommand(Validate)
-    .addCommand(Migrate)
-    .addCommand(Logs)
-    .addCommand(Search)
-    .addCommand(Why)
-    .addCommand(Reproduce)
-    .addCommand(Timing)
-    .addCommand(Tests)
-    .addCommand(Rerun)
-    .addCommand(Spend)
-    .addCommand(Dispatch)
-    .addCommand(Runner)
-    .addCommand(Cache)
-    .addCommand(Artifact)
-    .addCommand(Environment)
-    .addCommand(Deployment)
-    .addCommand(Approval)
-    .addCommand(Schedule)
-    .addCommand(Oidc)
-    .addCommand(Actions)
-    .addCommand(Terms)
-    .addCommand(Tenant)
-    .addCommand(Notify)
-    .addCommand(Login)
-    .addCommand(Logout)
-    .addCommand(Whoami)
-    .addCommand(Secret)
-    .addCommand(Variable)
-    .addCommand(Lsp);
-program.parse(process.argv);
+buildProgram(readVersion()).parse(process.argv);

package/dist/cli/program.js

@@ -0,0 +1,74 @@
+import { Command } from 'commander';
+import Run from './run/main.js';
+import Validate from './validate/main.js';
+import Migrate from './migrate/main.js';
+import Logs from './logs/main.js';
+import Search from './search/main.js';
+import Why from './why/main.js';
+import Reproduce from './reproduce/main.js';
+import Timing from './timing/main.js';
+import Tests from './tests/main.js';
+import Rerun from './rerun/main.js';
+import Spend from './spend/main.js';
+import Dispatch from './dispatch/main.js';
+import Runner from './runner/main.js';
+import Cache from './cache/main.js';
+import Artifact from './artifact/main.js';
+import Environment from './environment/main.js';
+import Deployment from './deployment/main.js';
+import Approval from './approval/main.js';
+import Schedule from './schedule/main.js';
+import Oidc from './oidc/main.js';
+import Actions from './actions/main.js';
+import Terms from './terms/main.js';
+import Tenant from './tenant/main.js';
+import Notify from './notify/main.js';
+import Lsp from './lsp/main.js';
+import Login from './login/main.js';
+import Logout from './logout/main.js';
+import Whoami from './whoami/main.js';
+import Secret from './secret/main.js';
+import Variable from './variable/main.js';
+import Token from './token/main.js';
+/**
+ * The `apex` command tree, without parsing anything.
+ *
+ * Split from `main.ts` so the tree can be read as data: `test/cli-reference.test.ts`
+ * walks it to write the structured reference the public docs render, and a test
+ * can build it without a process to parse.
+ */
+export const buildProgram = (version) => new Command()
+    .name('apex')
+    .description('Apex Actions — developer and operator CLI')
+    .version(version)
+    .addCommand(Run)
+    .addCommand(Validate)
+    .addCommand(Migrate)
+    .addCommand(Logs)
+    .addCommand(Search)
+    .addCommand(Why)
+    .addCommand(Reproduce)
+    .addCommand(Timing)
+    .addCommand(Tests)
+    .addCommand(Rerun)
+    .addCommand(Spend)
+    .addCommand(Dispatch)
+    .addCommand(Runner)
+    .addCommand(Cache)
+    .addCommand(Artifact)
+    .addCommand(Environment)
+    .addCommand(Deployment)
+    .addCommand(Approval)
+    .addCommand(Schedule)
+    .addCommand(Oidc)
+    .addCommand(Actions)
+    .addCommand(Terms)
+    .addCommand(Tenant)
+    .addCommand(Notify)
+    .addCommand(Login)
+    .addCommand(Logout)
+    .addCommand(Whoami)
+    .addCommand(Token)
+    .addCommand(Secret)
+    .addCommand(Variable)
+    .addCommand(Lsp);

package/dist/cli/reference.js

@@ -0,0 +1,139 @@
+/**
+ * How the public CLI reference presents each top-level command: which group it
+ * sits in, who it is for, and a few examples a person can copy.
+ *
+ * `test/cli-reference.test.ts` walks `buildProgram` and writes
+ * `docs/feature-docs/cli-reference.json` from the tree plus this table; the
+ * marketing site renders that file. A top-level command missing from here
+ * fails the test, so nothing reaches the site — or escapes it — unclassified.
+ *
+ * **`audience` is what a customer can run today, not what the command is
+ * for.** A customer's credential is an API token whose one scope is
+ * repository secrets and variables, plus its own identity and tokens
+ * (control-plane ADR-0064); every other control-plane route answers it 403. So
+ * a command that calls one of those routes is `operator` until its route opens
+ * to customers, however customer-shaped it looks — publishing it would sell
+ * something the product refuses. Local commands need no control plane.
+ */
+/** The reference's sections, in the order a person meets them. */
+export const GROUPS = [
+    { id: 'setup', title: 'Sign in and tokens' },
+    { id: 'local', title: 'Run locally' },
+    { id: 'runs', title: 'Runs and logs' },
+    { id: 'config', title: 'Repository configuration' },
+    { id: 'storage', title: 'Caches and artifacts' },
+    { id: 'runners', title: 'Runners' },
+    { id: 'billing', title: 'Usage and cost' },
+];
+/** Calls a control-plane route a customer token is refused on. */
+const OPERATOR_TODAY = 'operator';
+export const REFERENCE = {
+    login: {
+        group: 'setup',
+        audience: 'customer',
+        examples: [
+            { command: 'apex login', description: 'Sign in through the browser; the token is saved for your user only.' },
+            { command: 'apex login --no-browser', description: 'On a machine without a browser: print the approval URL to open elsewhere.' },
+        ],
+    },
+    logout: {
+        group: 'setup',
+        audience: 'customer',
+        examples: [{ command: 'apex logout', description: 'Revoke the saved token on the server, then delete it.' }],
+    },
+    whoami: {
+        group: 'setup',
+        audience: 'customer',
+        examples: [
+            { command: 'apex whoami', description: 'Who the CLI acts as, with which credential, and when it expires.' },
+            { command: 'apex whoami --json', description: 'The same, for a script.' },
+        ],
+    },
+    token: {
+        group: 'setup',
+        audience: 'customer',
+        examples: [
+            {
+                command: 'apex token create deploy-bot --repo acme/web --expires-in-days 30',
+                description: 'Create a token held to one repository, approved in the browser, and print it once.',
+            },
+            { command: 'apex token list --all', description: 'Every token you hold, expired and revoked ones included.' },
+            { command: 'apex token revoke 0b6f1c2e-9d4a-4f7e-8a31-5c2d9e7b1a40', description: 'Revoke one token by the id apex token list shows; it stops working at once.' },
+        ],
+    },
+    run: {
+        group: 'local',
+        audience: 'customer',
+        examples: [
+            { command: 'apex run .github/workflows/ci.yml', description: 'Run a workflow on this machine with the same engine and executor as the service.' },
+            { command: 'apex run --job test --secret NPM_TOKEN', description: 'Run one job; NPM_TOKEN is read from your environment, never from the command line.' },
+            { command: 'apex run --event pull_request --payload event.json', description: 'Plan against a pull_request event with a payload you supply.' },
+        ],
+    },
+    validate: {
+        group: 'local',
+        audience: 'customer',
+        examples: [
+            { command: 'apex validate', description: 'Validate every workflow in .github/workflows/.' },
+            { command: 'apex validate .github/workflows/release.yml --json', description: 'Validate one file and print the diagnostics as JSON.' },
+        ],
+    },
+    lsp: {
+        group: 'local',
+        audience: 'customer',
+        examples: [{ command: 'apex lsp', description: 'Start the workflow language server on stdio, for your editor to launch.' }],
+    },
+    migrate: {
+        group: 'local',
+        audience: 'customer',
+        // `coexist` opts a repository's workflows in on the control plane, which a customer token cannot reach yet.
+        operatorSubcommands: ['coexist'],
+        examples: [
+            { command: 'apex migrate scan acme', description: "Report what an organization's workflows would do on Apex Actions, read through the GitHub API." },
+            { command: 'apex migrate scan --path .', description: 'Scan a checkout on this machine instead.' },
+        ],
+    },
+    secret: {
+        group: 'config',
+        audience: 'customer',
+        // The organisation scope answers only for the operator's own organisation.
+        operatorOptions: ['--org'],
+        examples: [
+            { command: 'printf %s "$NPM_TOKEN" | apex secret set NPM_TOKEN --repo acme/web', description: 'Set a secret from a pipe; a value never goes on the command line.' },
+            { command: 'apex secret set DEPLOY_KEY --repo acme/web --repo acme/api --from-file key.pem', description: 'Set one value on two repositories, from a file.' },
+            { command: 'apex secret list --repo acme/web', description: "A repository's secret names — never values." },
+        ],
+    },
+    variable: {
+        group: 'config',
+        audience: 'customer',
+        operatorOptions: ['--org'],
+        examples: [
+            { command: 'apex variable set NODE_VERSION --value 24 --repo acme/web', description: 'Set a repository variable; a variable is not secret, so --value is allowed.' },
+            { command: 'apex variable list --repo acme/web --json', description: "A repository's variables and their values, as JSON." },
+        ],
+    },
+    // Commands whose routes refuse a customer token today: the operator's, until those routes open.
+    logs: { group: 'runs', audience: OPERATOR_TODAY },
+    search: { group: 'runs', audience: OPERATOR_TODAY },
+    why: { group: 'runs', audience: OPERATOR_TODAY },
+    reproduce: { group: 'runs', audience: OPERATOR_TODAY },
+    timing: { group: 'runs', audience: OPERATOR_TODAY },
+    tests: { group: 'runs', audience: OPERATOR_TODAY },
+    rerun: { group: 'runs', audience: OPERATOR_TODAY },
+    dispatch: { group: 'runs', audience: OPERATOR_TODAY },
+    environment: { group: 'config', audience: OPERATOR_TODAY },
+    deployment: { group: 'config', audience: OPERATOR_TODAY },
+    approval: { group: 'config', audience: OPERATOR_TODAY },
+    schedule: { group: 'config', audience: OPERATOR_TODAY },
+    notify: { group: 'config', audience: OPERATOR_TODAY },
+    actions: { group: 'config', audience: OPERATOR_TODAY },
+    oidc: { group: 'config', audience: OPERATOR_TODAY },
+    cache: { group: 'storage', audience: OPERATOR_TODAY },
+    artifact: { group: 'storage', audience: OPERATOR_TODAY },
+    runner: { group: 'runners', audience: OPERATOR_TODAY },
+    spend: { group: 'billing', audience: OPERATOR_TODAY },
+    // The operator's by design: the customer agreement's escalation path, and departed tenants' data.
+    terms: { group: 'billing', audience: 'operator' },
+    tenant: { group: 'billing', audience: 'operator' },
+};

package/dist/cli/tenant/main.js

@@ -15,7 +15,7 @@ const api = () => {
     }
 };
 const departuresCommand = new Command('departures')
-    .description('Every tenant that uninstalled, newest first, and when its data is deleted (control-plane ADR-0069)')
+    .description('Every tenant that uninstalled, newest first, and when its data is deleted')
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     const client = api();

package/dist/cli/token/main.js

@@ -0,0 +1,157 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createToken, listTokens, revokeTokens } from '../../src/application/manage-tokens.js';
+import { MAX_TOKEN_DAYS, TOKENS_PAGE, webBaseFor } from '../../src/domain/credentials.js';
+import { TOKEN_ENV, WEB_URL_ENV, apiUrlFrom } from '../../src/infrastructure/credentials.js';
+import { HttpLoginExchange, listenForCallback, newPkcePair, openInBrowser } from '../../src/infrastructure/loopback-login.js';
+import { api, collect, usage } from '../secret/shared.js';
+/**
+ * `apex token`: the person's API tokens from the terminal (control-plane
+ * ADR-0064, amended 2026-09-27).
+ *
+ * `create` asks for the person's approval in the browser, exactly as `apex
+ * login` does, and prints the token once — the token alone on stdout, so
+ * `$(apex token create …)` captures it, and everything a person reads on
+ * stderr. It is never saved, and the CLI's own login is left as it was.
+ * `list` and `revoke` use whichever credential the CLI already has.
+ *
+ * Exit codes follow §7: 0 done · 1 refused or declined · 2 usage · 3 no such token.
+ */
+const refused = (message) => {
+    console.error(chalk.red(message));
+    process.exitCode = 1;
+};
+const createCommand = new Command('create')
+    .description('Create an API token for a script or CI system, approved in the browser; the token is printed once and not saved')
+    .argument('<name>', 'what the token is for, as the token list will show it (1–100 characters)')
+    .option('--expires-in-days <days>', `days until the token expires, 1–${MAX_TOKEN_DAYS} (default 30)`)
+    .option('--repo <owner/repo>', 'hold the token to this repository (repeatable, up to 100); omit for every repository you administer', collect, [])
+    .option('--no-browser', 'print the approval URL instead of opening a browser')
+    .option('--json', 'print the token and its details as JSON on stdout')
+    .action(async (name, opts) => {
+    const days = opts.expiresInDays === undefined ? undefined : /^[0-9]+$/.test(opts.expiresInDays) ? Number(opts.expiresInDays) : Number.NaN;
+    const apiUrl = apiUrlFrom();
+    const outcome = await createToken({
+        pkce: newPkcePair,
+        listen: (state) => listenForCallback(state),
+        openBrowser: opts.browser ? (url) => openInBrowser(url) : undefined,
+        announce: (url) => {
+            console.error(opts.browser ? 'Opening the browser to approve this token. If it does not open, visit:' : 'Open this URL to approve this token:');
+            console.error(`  ${url}`);
+            console.error(chalk.dim('Waiting for the approval (5 minutes)…'));
+        },
+        exchange: new HttpLoginExchange(apiUrl),
+        webBase: webBaseFor(apiUrl, process.env[WEB_URL_ENV]),
+    }, { name, days, repos: opts.repo });
+    switch (outcome.kind) {
+        case 'created': {
+            if (opts.json === true) {
+                console.log(JSON.stringify({ token: outcome.token, id: outcome.id, name: outcome.name, login: outcome.login, expiresAt: outcome.expiresAt, repos: outcome.repos ?? null }, null, 2));
+            }
+            else {
+                console.log(outcome.token);
+            }
+            const reach = outcome.repos === undefined || outcome.repos.length === 0 ? 'every repository you administer' : outcome.repos.join(', ');
+            console.error(`${chalk.green('✔')} created "${outcome.name}" for ${outcome.login} — ${reach}; expires ${outcome.expiresAt}`);
+            console.error(chalk.yellow('This is the only time the token is shown. Store it now — in your CI system as a secret named APEX_TOKEN.'));
+            return;
+        }
+        case 'invalid':
+            usage(outcome.detail);
+            return;
+        case 'denied':
+            refused(`declined in the browser: ${outcome.detail}`);
+            return;
+        case 'state-mismatch':
+            refused('a callback arrived that did not belong to this request, so it was refused; run apex token create again');
+            return;
+        case 'malformed':
+            refused('the browser came back without a code; run apex token create again');
+            return;
+        case 'timeout':
+            refused('no approval arrived within 5 minutes; run apex token create again');
+            return;
+        case 'refused':
+            refused(outcome.detail);
+            return;
+    }
+});
+const reachOf = (t) => (t.repos === undefined || t.repos.length === 0 ? 'all administered' : t.repos.join(', '));
+const day = (iso) => (iso === undefined ? '—' : iso.slice(0, 10));
+const listCommand = new Command('list')
+    .description('Your API tokens — names and last four characters, never the tokens')
+    .option('--all', 'include expired and revoked tokens')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listTokens(client, opts.all === true);
+    if (outcome.kind === 'refused') {
+        refused(outcome.detail);
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify({ tokens: outcome.tokens }, null, 2));
+        return;
+    }
+    if (outcome.tokens.length === 0) {
+        console.log(chalk.yellow(outcome.hidden > 0 ? `No active tokens (${outcome.hidden} expired or revoked; --all shows them).` : 'You hold no tokens.'));
+        return;
+    }
+    const rows = outcome.tokens.map((t) => [
+        `${t.current === true ? '* ' : '  '}${t.name}`,
+        t.id,
+        `…${t.last4}`,
+        t.source,
+        reachOf(t),
+        day(t.createdAt),
+        day(t.expiresAt),
+        day(t.lastUsedAt),
+        t.state,
+    ]);
+    const header = ['  NAME', 'ID', 'LAST 4', 'SOURCE', 'REPOSITORIES', 'CREATED', 'EXPIRES', 'LAST USED', 'STATE'];
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const line = (cells) => cells.map((c, i) => c.padEnd(widths[i] ?? 0)).join('  ').trimEnd();
+    console.log(chalk.dim(line(header)));
+    for (const r of rows)
+        console.log(line(r));
+    if (outcome.tokens.some((t) => t.current === true))
+        console.log(chalk.dim('* the token this CLI is using'));
+    if (outcome.hidden > 0)
+        console.log(chalk.dim(`${outcome.hidden} expired or revoked not shown; --all shows them.`));
+});
+const revokeCommand = new Command('revoke')
+    .description('Revoke one of your API tokens by id, or all of them; it stops working immediately')
+    .argument('[id]', 'the token id, from apex token list')
+    .option('--all', 'revoke every token you hold, including the one this CLI is using')
+    .action(async (id, opts) => {
+    if ((id === undefined) === (opts.all !== true)) {
+        usage('name one token id, or pass --all');
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await revokeTokens(client, id === undefined ? { all: true } : { id });
+    switch (outcome.kind) {
+        case 'revoked':
+            console.log(`${chalk.green('✔')} revoked ${outcome.count} ${outcome.count === 1 ? 'token' : 'tokens'}`);
+            if (outcome.includedCurrent) {
+                console.log(chalk.yellow(`That included the token this CLI was using, so its next command will be refused. Run apex login again${process.env[TOKEN_ENV] ? `, or set ${TOKEN_ENV} to another token` : ''}.`));
+            }
+            return;
+        case 'not-found':
+            console.error(chalk.red(`no active token with id ${outcome.id} — apex token list shows yours`));
+            process.exitCode = 3;
+            return;
+        case 'refused':
+            refused(outcome.detail);
+            return;
+    }
+});
+export default new Command('token')
+    .description(`API tokens for scripts and CI: create one (approved in the browser), list yours, revoke one. Also on the dashboard at ${TOKENS_PAGE}`)
+    .addCommand(createCommand)
+    .addCommand(listCommand)
+    .addCommand(revokeCommand);

package/dist/cli/whoami/main.js

@@ -9,7 +9,13 @@ const credentialLine = (credential) => {
         return 'unknown';
     if (credential.kind !== 'token')
         return credential.kind === 'machine' ? 'the machine token (operator)' : 'a signed-in session';
-    const source = credential.source === 'login' ? 'minted by apex login' : credential.source === 'dashboard' ? 'minted on the dashboard' : 'a token';
+    const source = credential.source === 'login'
+        ? 'minted by apex login'
+        : credential.source === 'cli'
+            ? 'minted by apex token create'
+            : credential.source === 'dashboard'
+                ? 'minted on the dashboard'
+                : 'a token';
     return `token, ${source}${credential.expiresAt === undefined ? '' : `, expires ${credential.expiresAt}`}`;
 };
 /**

package/dist/src/application/authenticate.js

@@ -1,28 +1,38 @@
 import { authorizeUrl } from '../domain/credentials.js';
-export const login = async (deps) => {
+/**
+ * The loopback flow itself: open the consent page, wait for the one callback,
+ * redeem its code with the verifier. Shared by `apex login`, which saves what
+ * it gets, and `apex token create`, which hands it back to be printed once.
+ */
+export const approveInBrowser = async (deps, token) => {
     const pair = deps.pkce();
     const listener = await deps.listen(pair.state);
     try {
-        const url = authorizeUrl(deps.webBase, { port: listener.port, state: pair.state, codeChallenge: pair.challenge, name: deps.name });
+        const url = authorizeUrl(deps.webBase, { port: listener.port, state: pair.state, codeChallenge: pair.challenge, name: deps.name, token });
         deps.announce(url);
         deps.openBrowser?.(url);
         const callback = await listener.wait();
         if (callback.kind !== 'code')
             return callback;
-        let minted;
         try {
-            minted = await deps.exchange.redeem(callback.code, pair.verifier);
+            return { kind: 'minted', minted: await deps.exchange.redeem(callback.code, pair.verifier) };
         }
         catch (err) {
             return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
         }
-        await deps.store.save({ token: minted.token, login: minted.login, apiUrl: deps.apiUrl, expiresAt: minted.expiresAt });
-        return { kind: 'logged-in', login: minted.login, expiresAt: minted.expiresAt, location: deps.store.location };
     }
     finally {
         await listener.close();
     }
 };
+export const login = async (deps) => {
+    const approval = await approveInBrowser(deps);
+    if (approval.kind !== 'minted')
+        return approval;
+    const { minted } = approval;
+    await deps.store.save({ token: minted.token, login: minted.login, apiUrl: deps.apiUrl, expiresAt: minted.expiresAt });
+    return { kind: 'logged-in', login: minted.login, expiresAt: minted.expiresAt, location: deps.store.location };
+};
 /**
  * Revoke the saved token at the control plane that minted it, then forget it
  * (control-plane ADR-0064: a token may revoke itself and nothing else). The file

package/dist/src/application/manage-tokens.js

@@ -0,0 +1,65 @@
+// application layer — see ../../../../docs/conventions.md §1
+import { tokenRequestProblem } from '../domain/credentials.js';
+import { approveInBrowser } from './authenticate.js';
+const detail = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * Mint a token through the browser. The flags are checked before a browser
+ * opens, so a typo costs nothing; the control plane checks them again.
+ */
+export const createToken = async (deps, input) => {
+    const name = input.name.trim();
+    const problem = tokenRequestProblem(name, input.days, input.repos);
+    if (problem !== undefined)
+        return { kind: 'invalid', detail: problem };
+    const approval = await approveInBrowser({ ...deps, name }, { ...(input.days === undefined ? {} : { days: input.days }), ...(input.repos.length === 0 ? {} : { repos: input.repos }) });
+    if (approval.kind !== 'minted')
+        return approval;
+    const { minted } = approval;
+    return {
+        kind: 'created',
+        token: minted.token,
+        login: minted.login,
+        expiresAt: minted.expiresAt,
+        id: minted.id,
+        name: minted.name ?? name,
+        repos: minted.repos,
+    };
+};
+/** The person's tokens, newest first; only the active ones unless `all`. */
+export const listTokens = async (api, all) => {
+    let tokens;
+    try {
+        tokens = await api.listTokens();
+    }
+    catch (err) {
+        return { kind: 'refused', detail: detail(err) };
+    }
+    const shown = all ? tokens : tokens.filter((t) => t.state === 'active');
+    return { kind: 'listed', tokens: shown, hidden: tokens.length - shown.length };
+};
+/**
+ * Revoke one token by id, or every token with `all`. Asks for the list first
+ * only to say whether the CLI just revoked its own credential, which is the one
+ * outcome a person would otherwise discover on their next command.
+ */
+export const revokeTokens = async (api, target) => {
+    let current;
+    try {
+        current = (await api.listTokens()).find((t) => t.current === true && t.state === 'active')?.id;
+    }
+    catch {
+        // Not knowing which one is ours does not stop the revocation.
+    }
+    try {
+        if ('all' in target) {
+            const count = await api.revokeAllTokens();
+            return { kind: 'revoked', count, includedCurrent: current !== undefined };
+        }
+        if (!(await api.revokeToken(target.id)))
+            return { kind: 'not-found', id: target.id };
+        return { kind: 'revoked', count: 1, includedCurrent: current === target.id };
+    }
+    catch (err) {
+        return { kind: 'refused', detail: detail(err) };
+    }
+};

package/dist/src/domain/credentials.js

@@ -50,7 +50,11 @@ export const parseSavedCredential = (raw) => {
             return undefined;
     return { token: r['token'], login: r['login'], apiUrl: r['apiUrl'], expiresAt: r['expiresAt'] };
 };
-/** The consent page `apex login` opens (RFC 8252 loopback, RFC 7636 S256). */
+/**
+ * The consent page `apex login` and `apex token create` open (RFC 8252
+ * loopback, RFC 7636 S256). A token request adds `purpose=token` and what the
+ * person is approving, so the page can show it and the code carries it.
+ */
 export const authorizeUrl = (webBase, request) => {
     const query = new URLSearchParams({
         port: String(request.port),
@@ -58,8 +62,34 @@ export const authorizeUrl = (webBase, request) => {
         code_challenge: request.codeChallenge,
         name: request.name,
     });
+    if (request.token !== undefined) {
+        query.set('purpose', 'token');
+        if (request.token.days !== undefined)
+            query.set('days', String(request.token.days));
+        if (request.token.repos !== undefined && request.token.repos.length > 0)
+            query.set('repos', request.token.repos.join(','));
+    }
     return `${normaliseUrl(webBase)}/cli/authorize?${query.toString()}`;
 };
+/** A token's lifetime bounds (control-plane ADR-0064): every token expires, 90 days at most. */
+export const MAX_TOKEN_DAYS = 90;
+/** Repositories one token may be held to. */
+export const MAX_TOKEN_REPOS = 100;
+const REPO = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/;
+/** `apex token create`'s flags, checked before a browser opens — the control plane checks them again. */
+export const tokenRequestProblem = (name, days, repos) => {
+    if (name.trim() === '' || name.trim().length > 100)
+        return 'a token needs a name of 1 to 100 characters';
+    if (days !== undefined && !(Number.isInteger(days) && days >= 1 && days <= MAX_TOKEN_DAYS)) {
+        return `--expires-in-days must be a whole number from 1 to ${MAX_TOKEN_DAYS}`;
+    }
+    if (repos.length > MAX_TOKEN_REPOS)
+        return `a token may name at most ${MAX_TOKEN_REPOS} repositories`;
+    const bad = repos.filter((r) => !REPO.test(r));
+    if (bad.length > 0)
+        return `not owner/repo: ${bad.join(', ')}`;
+    return undefined;
+};
 /**
  * Judge what arrived at the loopback callback.
  *

package/dist/src/infrastructure/control-plane-http.js

@@ -55,6 +55,21 @@ export class HttpControlPlane {
     async whoami() {
         return await this.#json('GET', '/api/v1/me');
     }
+    // ── the person's tokens: read and revoke, never mint (ADR-0064, amended 2026-09-27) ──
+    async listTokens() {
+        return (await this.#json('GET', '/api/v1/me/tokens')).tokens;
+    }
+    async revokeToken(id) {
+        const response = await this.#request('DELETE', `/api/v1/me/tokens/${encodeURIComponent(id)}`);
+        if (response.status === 404)
+            return false;
+        if (!response.ok)
+            throw new HttpError(await this.#errorMessage(response), response.status);
+        return true;
+    }
+    async revokeAllTokens() {
+        return (await this.#json('DELETE', '/api/v1/me/tokens')).revoked;
+    }
     // ── secrets and variables (values are write-only) ──
     async listSecrets(target) {
         const body = await this.#json('GET', `${this.#scopePath(target)}/secrets`);

package/dist/src/infrastructure/loopback-login.js

@@ -56,10 +56,10 @@ export const listenForCallback = async (expectedState, timeoutMs = LOGIN_TIMEOUT
         const verdict = judgeCallback(url.searchParams, expectedState);
         switch (verdict.kind) {
             case 'code':
-                answer(res, 200, page('Signed in', 'The <code>apex</code> CLI is signed in. You can close this tab.'));
+                answer(res, 200, page('Approved', 'The <code>apex</code> CLI has what you approved. You can close this tab.'));
                 break;
             case 'denied':
-                answer(res, 200, page('Not signed in', 'The request was declined. You can close this tab.'));
+                answer(res, 200, page('Declined', 'The request was declined. You can close this tab.'));
                 break;
             case 'state-mismatch':
                 answer(res, 400, page('Not signed in', 'This callback does not belong to the login waiting in your terminal, so it was refused.'));
@@ -131,6 +131,13 @@ export class HttpLoginExchange {
         if (typeof body.token !== 'string' || typeof body.login !== 'string' || typeof body.expiresAt !== 'string') {
             throw new Error('the control plane answered the code exchange without a token');
         }
-        return { token: body.token, login: body.login, expiresAt: body.expiresAt };
+        return {
+            token: body.token,
+            login: body.login,
+            expiresAt: body.expiresAt,
+            ...(typeof body.id === 'string' ? { id: body.id } : {}),
+            ...(typeof body.name === 'string' ? { name: body.name } : {}),
+            ...(Array.isArray(body.repos) ? { repos: body.repos.filter((r) => typeof r === 'string') } : {}),
+        };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-actions/cli",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "license": "SEE LICENSE IN LICENSE",
   "//files": "Without this npm ships src, test and the CI config alongside the binary a user installs.",
   "files": [
@@ -49,6 +49,7 @@
     "test": "vitest run",
     "lint": "eslint . --max-warnings=0",
     "lint:arch": "depcruise src cli --config .dependency-cruiser.cjs",
-    "apex": "tsx cli/main.ts"
+    "apex": "tsx cli/main.ts",
+    "docs:reference": "APEX_UPDATE_GOLDEN=1 vitest run test/cli-reference.test.ts"
   }
 }