@apex-actions/cli 0.75.0 → 0.76.1

package/README.md

@@ -11,13 +11,16 @@ Part of the [Apex Actions](../) superproject. Conventions, architecture, and age
 | `apex run` | the runner binary, locally | `apex-runner` on `PATH` |
 | `apex validate` | the engine binary, locally | `apex-engine` on `PATH` |
 | `apex migrate scan` | the engine binary + the GitHub REST API | `apex-engine` on `PATH`; `GITHUB_TOKEN` unless `--path` |
-| `apex logs` | the control-plane REST API | a customer token with `actions:read` (`logs delete`: `actions:write`), or the operator token |
-| `apex dispatch` | the control-plane REST API | a customer token with `actions:write`, or the operator token |
+| `apex logs` | the control-plane REST API | a customer token with `actions:read` (`logs delete`: `actions:write`), or the machine token |
+| `apex dispatch` | the control-plane REST API | a customer token with `actions:write`, or the machine 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 edit` | the control-plane REST API; the browser to widen | a customer token to narrow; a person signed in to the dashboard to widen |
 | `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 with `secrets:*` / `variables:*` (`APEX_TOKEN` or `apex login`) |
+| `apex login --console` · `logout --console` | the Admin Console in the browser, and the control-plane REST API | an operator signed in to the Admin Console, who approves it |
+| `apex grant list` · `apex tenant installations` | the control-plane admin API | the operator token (`apex login --console`), or the machine token |
+| `apex grant create` · `update` · `revoke` | the control-plane admin API | the operator token (`apex login --console`) — never the machine token (control-plane ADR-0056, ADR-0079) |
 
 Every other customer command in `cli/reference.ts` names the permission it needs; the public reference shows it.
 
@@ -27,7 +30,7 @@ customer commands only, classified in `cli/reference.ts`).
 
 ```bash
 export APEX_API_URL=https://apex.example
-export APEX_ADMIN_TOKEN=…                       # the operator token, not a person's session
+export APEX_ADMIN_TOKEN=…                       # the machine token, not a person's session
 
 apex dispatch .github/workflows/deploy.yml --repo octo/app --ref main --input environment=production
 apex logs latest --repo octo/app --follow  # exits non-zero if the run failed
@@ -60,11 +63,25 @@ the file**:
    refuses a private key;
 4. otherwise the command stops with exit 2, naming `APEX_TOKEN` and `apex login`.
 
+**Operator commands** — `apex grant` and `apex tenant installations` — look first for the **operator
+token** `apex login --console` saved in `$XDG_CONFIG_HOME/apex/console-credentials` (same mode rules), when
+it is unexpired and was minted by the control plane `APEX_API_URL` names, and otherwise use the order above
+(control-plane ADR-0079). The operator token is approved on the Admin Console (`APEX_CONSOLE_URL`, or the
+API's `app.` host read as `admin.`) by an operator, by loopback only; it lives a week at most and reaches
+only the grant routes and the installation list, and every grant it writes names its operator. The machine
+token can list grants and is refused every write. `apex logout --console` revokes and forgets it.
+
 `APEX_API_URL` selects the control plane (default `https://app.apexactions.com`); a saved login is
 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); once the code is redeemed it hands the tab back to the web app's bare `/cli/done`
-page (control-plane ADR-0075). A customer token carries **permissions** (`resource:read|write`, write implying
+page (control-plane ADR-0075). Where no browser can open on this machine — an SSH session
+(`SSH_CONNECTION`/`SSH_TTY`), a Codespace, a dev container, `/.dockerenv`, or Linux with neither `DISPLAY`
+nor `WAYLAND_DISPLAY` — or with `--device` (or `--no-browser`), it uses the **device flow** instead (RFC 8628,
+run by Apex): it prints a code and `…/cli/device`, the person enters the code on any device, a phone included,
+and the CLI polls — honouring `interval` and `slow_down` — until the approval, a denial or the code's ten
+minutes end. `--browser` insists on the loopback. `apex token create` and a widening `apex token edit` take
+the same three flags. A customer token carries **permissions** (`resource:read|write`, write implying
 read; resources `actions`, `approvals`, `deployments`, `secrets`, `variables`, `environments`, `notifications`,
 `administration`) and belongs to **one Account** (control-plane ADR-0071). It reaches the repository routes its
 grants cover, within its person's role and the Account owner's token policy; `apex login` takes the policy's
@@ -78,6 +95,7 @@ print the new one, once.
 
 ```bash
 apex login                                                   # once per machine
+apex login --device                                          # over SSH: approve from a phone with the printed code
 printf %s "$TOKEN" | apex secret set ETS_PACKAGES_TOKEN --repo acme/api --repo acme/web
 apex secret set DEPLOY_KEY --repo acme/api --from-file ./deploy.key
 apex variable set AWS_REGION --value eu-west-1 --repo acme/api

package/dist/cli/grant/main.js

@@ -0,0 +1,141 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createGrant, listGrants, revokeGrant, updateGrant } from '../../src/application/manage-grants.js';
+import { createGrantBody, createdLine, grantLine, revokedLine, updateGrantBody } from '../../src/domain/grants.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+/**
+ * `apex grant`: complimentary access from the terminal (control-plane ADR-0056 as amended by ADR-0079,
+ * TASK-0199). The admin API's own shapes, unchanged. Every write needs a person: the operator token
+ * `apex login --console` saved, whose operator the grant row and the audit log name. The machine token
+ * (`APEX_ADMIN_TOKEN`) can list and is refused every write, so a leaked one cannot make a free tenant.
+ */
+/** The operator's API client — the saved operator token first — or explain what is missing and stop. */
+export const operatorApi = () => {
+    try {
+        return new HttpControlPlane({ operator: true });
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof NotConfiguredError ? `${err.message}; operators sign in with apex login --console` : String(err)));
+        process.exitCode = 2;
+        return undefined;
+    }
+};
+/** A refusal to stderr and exit 1, or the value. */
+const settled = (outcome) => {
+    if (outcome.kind === 'ok')
+        return outcome.value;
+    console.error(chalk.red(outcome.message));
+    process.exitCode = 1;
+    return undefined;
+};
+/** A flag problem: exit 2 (§7), before any round trip. */
+const usage = (problem) => {
+    console.error(chalk.red(problem));
+    process.exitCode = 2;
+};
+const listCommand = new Command('list')
+    .description('Every grant ever made, newest first: how each stands, the month so far, who granted it and why')
+    .option('--active', 'only grants that are open now')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const client = operatorApi();
+    if (!client)
+        return;
+    const grants = settled(await listGrants(client));
+    if (grants === undefined)
+        return;
+    const shown = opts.active === true ? grants.filter((g) => g.state === 'active') : grants;
+    if (opts.json === true) {
+        console.log(JSON.stringify(shown, null, 2));
+        return;
+    }
+    if (shown.length === 0) {
+        console.log(opts.active === true ? 'no grant is open' : 'no complimentary access has been granted');
+        return;
+    }
+    for (const g of shown)
+        console.log(`  ${grantLine(g)}`);
+});
+const createCommand = new Command('create')
+    .description('Grant an installation complimentary access, replacing any open grant it holds — recorded against you')
+    .argument('<installationId>', 'the GitHub App installation (see: apex tenant installations --fresh)')
+    .requiredOption('--minutes <n>', 'standard minutes per calendar month, 1 to 120,000')
+    .requiredOption('--concurrency <n>', 'jobs at once, 1 to 50')
+    .requiredOption('--reason <text>', 'who this is for and why they run free, up to 500 characters — stored on the grant')
+    .option('--until <YYYY-MM-DD>', 'the grant ends at the end of that UTC day (default: open-ended)')
+    .option('--json', 'machine-readable output')
+    .action(async (installation, opts) => {
+    const body = createGrantBody(installation, opts, new Date());
+    if (!body.ok) {
+        usage(body.problem);
+        return;
+    }
+    const client = operatorApi();
+    if (!client)
+        return;
+    const created = settled(await createGrant(client, body.value));
+    if (created === undefined)
+        return;
+    if (opts.json === true) {
+        console.log(JSON.stringify(created, null, 2));
+        return;
+    }
+    console.log(`${chalk.green('✔')} ${createdLine(created)}`);
+    console.log(`  ${grantLine(created.grant)}`);
+});
+const updateCommand = new Command('update')
+    .description("Change an open grant's minutes, jobs at once or end date — it takes effect on the next admission and claim")
+    .argument('<grantId>', 'the grant (see: apex grant list)')
+    .option('--minutes <n>', 'standard minutes per calendar month, 1 to 120,000')
+    .option('--concurrency <n>', 'jobs at once, 1 to 50')
+    .option('--until <YYYY-MM-DD>', 'end at the end of that UTC day')
+    .option('--no-end', 'remove the end date, making the grant open-ended')
+    .option('--json', 'machine-readable output')
+    .action(async (id, opts) => {
+    // Commander reads `--no-end` as `end: false`; anything else leaves `end` at its default, true.
+    const body = updateGrantBody({ minutes: opts.minutes, concurrency: opts.concurrency, until: opts.until, noEnd: opts.end === false }, new Date());
+    if (!body.ok) {
+        usage(body.problem);
+        return;
+    }
+    const client = operatorApi();
+    if (!client)
+        return;
+    const grant = settled(await updateGrant(client, id, body.value));
+    if (grant === undefined)
+        return;
+    if (opts.json === true) {
+        console.log(JSON.stringify(grant, null, 2));
+        return;
+    }
+    console.log(`${chalk.green('✔')} Changed the grant for ${grant.owner}.`);
+    console.log(`  ${grantLine(grant)}`);
+});
+const revokeCommand = new Command('revoke')
+    .description('End a grant now: new runs are refused, queued free work is cancelled with a reason, and running work finishes')
+    .argument('<grantId>', 'the grant (see: apex grant list)')
+    .option('--yes', 'confirm — revoking cannot be undone; the organisation does not fall back to the pre-trial minutes')
+    .option('--json', 'machine-readable output')
+    .action(async (id, opts) => {
+    if (opts.yes !== true) {
+        usage(`revoking ends the grant now and cannot be undone — re-run with --yes to revoke ${id}`);
+        return;
+    }
+    const client = operatorApi();
+    if (!client)
+        return;
+    const revoked = settled(await revokeGrant(client, id));
+    if (revoked === undefined)
+        return;
+    if (opts.json === true) {
+        console.log(JSON.stringify(revoked, null, 2));
+        return;
+    }
+    console.log(`${chalk.green('✔')} ${revokedLine(revoked)}`);
+});
+export default new Command('grant')
+    .description('Complimentary access: list, grant, change and revoke — every write is recorded against the operator signed in with apex login --console')
+    .addCommand(listCommand)
+    .addCommand(createCommand)
+    .addCommand(updateCommand)
+    .addCommand(revokeCommand);

package/dist/cli/login/device.js

@@ -0,0 +1,43 @@
+import chalk from 'chalk';
+import { chooseFlow, deviceInstructions } from '../../src/domain/credentials.js';
+import { HttpDeviceExchange, detectHeadless, machineReport, sleep } from '../../src/infrastructure/device-login.js';
+/**
+ * How `apex login`, `apex token create` and a widening `apex token edit` get their approval back
+ * (control-plane ADR-0075): the loopback redirect where a browser opens on this machine, a device code
+ * typed on any device where one cannot. One set of flags for the three commands.
+ */
+export const withFlowOptions = (command) => command
+    .option('--device', 'approve on any device — a phone included — by entering the code this prints at the address it prints')
+    .option('--browser', 'open a browser on this machine to approve, even where the CLI would choose a device code (SSH, a container, a Codespace)')
+    .option('--no-browser', 'the same as --device: print a code to enter on any device instead of opening a browser here');
+/** The chosen flow, and the device flow's dependencies when that is it; or the flags' problem. */
+export const approvalFlow = (flags, apiUrl, print) => {
+    const choice = chooseFlow(flags, detectHeadless());
+    if ('problem' in choice)
+        return choice;
+    if (choice.flow === 'loopback')
+        return { flow: 'loopback' };
+    const machine = machineReport();
+    return {
+        flow: 'device',
+        why: choice.why,
+        device: {
+            exchange: new HttpDeviceExchange(apiUrl),
+            announceCode: (start, why) => {
+                const [reason, open, expires] = why === undefined ? [undefined, ...deviceInstructions(start)] : deviceInstructions(start, why);
+                if (reason !== undefined)
+                    print(chalk.dim(reason));
+                if (open !== undefined)
+                    print(open);
+                if (expires !== undefined)
+                    print(chalk.dim(expires));
+                print(chalk.dim('Waiting for the approval…'));
+            },
+            sleep,
+            now: () => Date.now(),
+            why: choice.why,
+            os: machine.os,
+            hostname: machine.hostname,
+        },
+    };
+};

package/dist/cli/login/main.js

@@ -1,41 +1,60 @@
 import { hostname } from 'node:os';
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { login } from '../../src/application/authenticate.js';
-import { TOKENS_PAGE, describeGrants, webBaseFor } from '../../src/domain/credentials.js';
-import { ADMIN_TOKEN_ENV, FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFrom, credentialsPath } from '../../src/infrastructure/credentials.js';
+import { consoleLogin, login } from '../../src/application/authenticate.js';
+import { OPERATOR_TOKEN_PREFIX, TOKENS_PAGE, consoleBaseFor, describeGrants, loopbackTimeoutHint, webBaseFor } from '../../src/domain/credentials.js';
+import { ADMIN_TOKEN_ENV, CONSOLE_URL_ENV, FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFrom, consoleCredentialsPath, credentialsPath, } from '../../src/infrastructure/credentials.js';
 import { HttpLoginExchange, listenForCallback, newPkcePair, openInBrowser } from '../../src/infrastructure/loopback-login.js';
+import { approvalFlow, withFlowOptions } from './device.js';
 /**
  * `apex login`: sign the CLI in with the browser a person already uses
  * (control-plane ADR-0064, RFC 8252 + PKCE). The token it mints is the same
  * one the dashboard mints, saved `0600` for this user alone.
  *
  * It opens a browser only because it was asked to — this command is the
- * asking — and prints the URL either way, for a machine where none opens.
+ * asking — and prints the URL either way. Where no browser can open on this
+ * machine (SSH, a container, a Codespace, a Linux box with no display), or
+ * with `--device`, it prints a code to enter on any device instead
+ * (control-plane ADR-0075); `--browser` insists on the browser here.
  *
  * The token carries the Account token policy's defaults for the person's role
  * there (the Owner's: everything), and belongs to that one Account — named with
  * `--account` when the person is in more than one (control-plane ADR-0071).
+ *
+ * `--console` is the operator's sign-in (control-plane ADR-0079): approved on the
+ * Admin Console by an operator, it saves an **operator token** beside the Account
+ * login — a week at most, reaching only complimentary access (`apex grant`).
  */
-export default new Command('login')
-    .description("Sign the CLI in through the browser; the token is saved for this user only and carries your Account's default permissions for your role")
+export default withFlowOptions(new Command('login')
+    .description("Sign the CLI in through the browser — on this machine, or on any device with a code; the token is saved for this user only and carries your Account's default permissions for your role")
     .option('--account <id>', 'the Account to sign in to — needed when you belong to more than one')
-    .option('--no-browser', 'print the URL to open instead of opening a browser')
-    .action(async (opts) => {
+    .option('--console', 'sign in as an operator, approved on the Admin Console: an operator token for apex grant, a week at most, saved beside the Account login')).action(async (opts) => {
+    if (opts.console === true) {
+        await consoleSignIn(opts);
+        return;
+    }
     const apiUrl = apiUrlFrom();
     const webBase = webBaseFor(apiUrl, process.env[WEB_URL_ENV]);
     const store = new FileCredentialStore(credentialsPath());
+    const chosen = approvalFlow(opts, apiUrl, (line) => console.log(line));
+    if ('problem' in chosen) {
+        console.error(chalk.red(chosen.problem));
+        process.exitCode = 2;
+        return;
+    }
     let outcome;
     try {
         outcome = await login({
             pkce: newPkcePair,
             listen: (state) => listenForCallback(state),
-            openBrowser: opts.browser ? (url) => openInBrowser(url) : undefined,
+            openBrowser: (url) => openInBrowser(url),
             announce: (url) => {
-                console.log(opts.browser ? 'Opening the browser to approve this login. If it does not open, visit:' : 'Open this URL to approve this login:');
+                console.log('Opening the browser to approve this login. If it does not open, visit:');
                 console.log(`  ${url}`);
                 console.log(chalk.dim('Waiting for the approval (5 minutes)…'));
             },
+            flow: chosen.flow,
+            device: chosen.device,
             exchange: new HttpLoginExchange(apiUrl),
             store,
             apiUrl,
@@ -49,37 +68,91 @@ export default new Command('login')
         process.exitCode = 1;
         return;
     }
+    if (outcome.kind !== 'logged-in') {
+        reportFailure(outcome, 'apex login');
+        return;
+    }
+    console.log(`${chalk.green('✔')} signed in as ${outcome.login} — the token expires ${outcome.expiresAt}`);
+    if (outcome.permissions !== undefined) {
+        console.log(`  permissions: ${describeGrants(outcome.permissions)}${outcome.accountId === undefined ? '' : ` · Account ${outcome.accountId}`}`);
+    }
+    console.log(chalk.dim(`Saved to ${outcome.location}. Revoke it any time at ${webBase}${TOKENS_PAGE}.`));
+    // The environment outranks the saved login (ADR-0005): say so, or the login looks like it did nothing.
+    for (const name of [TOKEN_ENV, ADMIN_TOKEN_ENV]) {
+        if (process.env[name])
+            console.log(chalk.yellow(`${name} is set in this shell and is used before the saved login; unset it to use the login.`));
+    }
+});
+/** Every way a login can end without a token, in words for the terminal. */
+const reportFailure = (outcome, command) => {
+    process.exitCode = 1;
     switch (outcome.kind) {
-        case 'logged-in':
-            console.log(`${chalk.green('✔')} signed in as ${outcome.login} — the token expires ${outcome.expiresAt}`);
-            if (outcome.permissions !== undefined) {
-                console.log(`  permissions: ${describeGrants(outcome.permissions)}${outcome.accountId === undefined ? '' : ` · Account ${outcome.accountId}`}`);
-            }
-            console.log(chalk.dim(`Saved to ${outcome.location}. Revoke it any time at ${webBase}${TOKENS_PAGE}.`));
-            // The environment outranks the saved login (ADR-0005): say so, or the login looks like it did nothing.
-            for (const name of [TOKEN_ENV, ADMIN_TOKEN_ENV]) {
-                if (process.env[name])
-                    console.log(chalk.yellow(`${name} is set in this shell and is used before the saved login; unset it to use the login.`));
-            }
-            return;
         case 'denied':
             console.error(chalk.red(`the login was not approved: ${outcome.detail}`));
-            process.exitCode = 1;
             return;
         case 'state-mismatch':
-            console.error(chalk.red('a callback arrived that this login did not ask for (its state did not match), so nothing was saved; run `apex login` again'));
-            process.exitCode = 1;
+            console.error(chalk.red(`a callback arrived that this login did not ask for (its state did not match), so nothing was saved; run \`${command}\` again`));
             return;
         case 'malformed':
-            console.error(chalk.red('the callback carried no code, so nothing was saved; run `apex login` again'));
-            process.exitCode = 1;
+            console.error(chalk.red(`the callback carried no code, so nothing was saved; run \`${command}\` again`));
             return;
         case 'timeout':
-            console.error(chalk.red('no approval arrived within 5 minutes; the approval page must be opened in a browser on this machine — run `apex login` again'));
-            process.exitCode = 1;
+            console.error(chalk.red(command === 'apex login --console' ? 'No approval arrived. An operator token is approved only in a browser on this machine, signed in to the Admin Console.' : loopbackTimeoutHint(command)));
+            return;
+        case 'expired':
+            console.error(chalk.red(`the code expired before anyone approved it, so nothing was saved; run \`${command}\` again for a new one`));
             return;
         case 'refused':
             console.error(chalk.red(`the control plane refused the login code: ${outcome.detail}`));
-            process.exitCode = 1;
     }
-});
+};
+/**
+ * `apex login --console` (control-plane ADR-0079): the loopback approval on the Admin Console, saving the
+ * operator token to its own file. No device flow — `--device` is refused rather than silently ignored.
+ */
+const consoleSignIn = async (opts) => {
+    if (opts.device === true || opts.browser === false || opts.account !== undefined) {
+        console.error(chalk.red('apex login --console takes no --device, --no-browser or --account: an operator token is approved in a browser on this machine, on the Admin Console'));
+        process.exitCode = 2;
+        return;
+    }
+    const apiUrl = apiUrlFrom();
+    const consoleBase = consoleBaseFor(apiUrl, process.env[CONSOLE_URL_ENV]);
+    if (consoleBase === undefined) {
+        console.error(chalk.red(`set ${CONSOLE_URL_ENV} to the Admin Console's address — it cannot be worked out from ${apiUrl}`));
+        process.exitCode = 2;
+        return;
+    }
+    const store = new FileCredentialStore(consoleCredentialsPath());
+    let outcome;
+    try {
+        outcome = await consoleLogin({
+            pkce: newPkcePair,
+            listen: (state) => listenForCallback(state),
+            openBrowser: (url) => openInBrowser(url),
+            announce: (url) => {
+                console.log('Opening the Admin Console to approve an operator token. If it does not open, visit:');
+                console.log(`  ${url}`);
+                console.log(chalk.dim('Waiting for the approval (5 minutes)…'));
+            },
+            exchange: new HttpLoginExchange(apiUrl),
+            store,
+            apiUrl,
+            webBase: consoleBase,
+            name: hostname().slice(0, 100) || 'apex CLI',
+            operatorPrefix: OPERATOR_TOKEN_PREFIX,
+        });
+    }
+    catch (err) {
+        console.error(chalk.red(`login failed: ${err instanceof Error ? err.message : String(err)}`));
+        process.exitCode = 1;
+        return;
+    }
+    if (outcome.kind !== 'logged-in') {
+        reportFailure(outcome, 'apex login --console');
+        return;
+    }
+    console.log(`${chalk.green('✔')} signed in as the operator ${outcome.login} — the operator token expires ${outcome.expiresAt}`);
+    console.log('  it reaches complimentary access only: apex grant list | create | update | revoke, and apex tenant installations');
+    console.log(chalk.dim(`Saved to ${outcome.location}. Revoke it with apex logout --console, or at ${consoleBase}/tokens.`));
+};

package/dist/cli/logout/main.js

@@ -1,9 +1,9 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { logout } from '../../src/application/authenticate.js';
-import { TOKENS_PAGE, webBaseFor } from '../../src/domain/credentials.js';
+import { TOKENS_PAGE, consoleBaseFor, webBaseFor } from '../../src/domain/credentials.js';
 import { HttpControlPlane } from '../../src/infrastructure/control-plane-http.js';
-import { ADMIN_TOKEN_ENV, FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFrom, credentialsPath } from '../../src/infrastructure/credentials.js';
+import { ADMIN_TOKEN_ENV, CONSOLE_URL_ENV, FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFrom, consoleCredentialsPath, credentialsPath, } from '../../src/infrastructure/credentials.js';
 /**
  * `apex logout`: revoke the token `apex login` saved, then forget it.
  *
@@ -12,12 +12,18 @@ import { ADMIN_TOKEN_ENV, FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFro
  * token may do to itself (control-plane ADR-0064). The file goes whether or not
  * the server could be reached; when it could not, the command says the token
  * may still be valid and where to revoke it, rather than implying it is dead.
+ *
+ * `--console` does the same to the operator token `apex login --console` saved
+ * (control-plane ADR-0079), which may revoke itself and nothing else.
  */
 export default new Command('logout')
     .description('Revoke the token `apex login` saved, and forget it')
-    .action(async () => {
-    const store = new FileCredentialStore(credentialsPath());
-    const tokensPage = `${webBaseFor(apiUrlFrom(), process.env[WEB_URL_ENV])}${TOKENS_PAGE}`;
+    .option('--console', 'revoke and forget the operator token `apex login --console` saved instead')
+    .action(async (opts) => {
+    const operator = opts.console === true;
+    const store = new FileCredentialStore(operator ? consoleCredentialsPath() : credentialsPath());
+    const consoleBase = consoleBaseFor(apiUrlFrom(), process.env[CONSOLE_URL_ENV]);
+    const tokensPage = operator ? `${consoleBase ?? 'the Admin Console'}/tokens` : `${webBaseFor(apiUrlFrom(), process.env[WEB_URL_ENV])}${TOKENS_PAGE}`;
     let outcome;
     try {
         outcome = await logout(store, (saved) => new HttpControlPlane({ baseUrl: saved.apiUrl, token: saved.token }).revokeCurrentToken());
@@ -28,7 +34,7 @@ export default new Command('logout')
         return;
     }
     if (outcome.kind === 'nothing') {
-        console.log(`No saved login at ${outcome.location}; nothing to forget.`);
+        console.log(`No saved ${operator ? 'operator token' : 'login'} at ${outcome.location}; nothing to forget.`);
     }
     else if (outcome.revoked === true) {
         console.log(`${chalk.green('✔')} revoked the saved token and removed ${outcome.location}`);
@@ -38,7 +44,7 @@ export default new Command('logout')
         console.log(chalk.yellow(`The token could not be revoked (${outcome.revoked.failed}) and may still be valid — revoke it at ${tokensPage}.`));
         process.exitCode = 1;
     }
-    for (const name of [TOKEN_ENV, ADMIN_TOKEN_ENV]) {
+    for (const name of operator ? [] : [TOKEN_ENV, ADMIN_TOKEN_ENV]) {
         if (process.env[name])
             console.log(chalk.yellow(`${name} is still set in this shell, and the CLI still uses it.`));
     }

package/dist/cli/program.js

@@ -22,6 +22,7 @@ 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 Grant from './grant/main.js';
 import Notify from './notify/main.js';
 import Lsp from './lsp/main.js';
 import Login from './login/main.js';
@@ -64,6 +65,7 @@ export const buildProgram = (version) => new Command()
     .addCommand(Actions)
     .addCommand(Terms)
     .addCommand(Tenant)
+    .addCommand(Grant)
     .addCommand(Notify)
     .addCommand(Login)
     .addCommand(Logout)

package/dist/cli/reference.js

@@ -43,13 +43,20 @@ export const REFERENCE = {
         examples: [
             { command: 'apex login', description: "Sign in through the browser; the token carries your Account's default permissions for your role, and is saved for your user only." },
             { command: 'apex login --account acc_4f2b9e', description: 'In more than one Account: name the one to sign in to.' },
-            { command: 'apex login --no-browser', description: 'On a machine without a browser: print the approval URL to open elsewhere.' },
+            {
+                command: 'apex login --device',
+                description: 'Over SSH, in a container or a Codespace: print a code to enter at app.apexactions.com/cli/device on any device — a phone included. Chosen by itself where no browser can open; --no-browser means the same.',
+            },
+            { command: 'apex login --browser', description: 'Open a browser on this machine even where the CLI would choose a code.' },
         ],
+        // The operator's sign-in, approved on the Admin Console (control-plane ADR-0079).
+        operatorOptions: ['--console'],
     },
     logout: {
         group: 'setup',
         audience: 'customer',
         examples: [{ command: 'apex logout', description: 'Revoke the saved token on the server, then delete it.' }],
+        operatorOptions: ['--console'],
     },
     whoami: {
         group: 'setup',
@@ -67,6 +74,10 @@ export const REFERENCE = {
                 command: 'apex token create deploy-bot --permission actions:write --permission secrets:write --repo acme/web --expires-in-days 30',
                 description: 'Create a token that may run workflows and set secrets on one repository, approved in the browser, and print it once.',
             },
+            {
+                command: 'apex token create ci-deploy --permission actions:write --device',
+                description: 'The same from a machine with no browser: approve it on any device with the code it prints; the token still prints only here.',
+            },
             {
                 command: 'apex token edit 0b6f1c2e-9d4a-4f7e-8a31-5c2d9e7b1a40 --remove-permission secrets:write',
                 description: 'Narrow a token: applies at once, from the terminal.',
@@ -295,4 +306,6 @@ export const REFERENCE = {
     runner: { group: 'runners', audience: OPERATOR },
     terms: { group: 'billing', audience: OPERATOR },
     tenant: { group: 'billing', audience: OPERATOR },
+    // Complimentary access: the operator token `apex login --console` saves writes; no Account token reaches it (control-plane ADR-0079).
+    grant: { group: 'billing', audience: OPERATOR },
 };

package/dist/cli/tenant/main.js

@@ -5,6 +5,8 @@ import { backfillAccounts, connectInstallation, listUnconnected } from '../../sr
 import { backfillLines, connectLine, unconnectedLine } from '../../src/domain/accounts.js';
 import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
 import { countsLine, departureLine } from '../../src/domain/departures.js';
+import { listInstallations } from '../../src/application/manage-grants.js';
+import { installationLine } from '../../src/domain/grants.js';
 /** Build the API client, or explain what is missing and stop. */
 const api = () => {
     try {
@@ -157,10 +159,44 @@ const connectCommand = new Command('connect')
     }
     console.log(`${chalk.green('✔')} ${connectLine(outcome.value)}`);
 });
+const installationsCommand = new Command('installations')
+    .description("Every installation of the App as GitHub lists it, with what Apex knows of each — --fresh for those the tenants list never shows, which a grant needs the id of")
+    .option('--fresh', 'only installations that never ran, paid or were granted')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    // The operator token `apex login --console` saved reaches this route too (control-plane ADR-0079).
+    let client;
+    try {
+        client = new HttpControlPlane({ operator: true });
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof NotConfiguredError ? err.message : String(err)));
+        process.exitCode = 2;
+        return;
+    }
+    const outcome = await listInstallations(client, opts.fresh === true);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.message));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify(outcome.value, null, 2));
+        return;
+    }
+    if (outcome.value.length === 0) {
+        console.log(chalk.green(opts.fresh === true ? 'no fresh installation — every one has run, paid or been granted' : 'GitHub lists no installation of the App'));
+        return;
+    }
+    for (const i of outcome.value)
+        console.log(`  ${installationLine(i)}`);
+    console.log(chalk.dim('\nGrant one with: apex grant create <installationId> --minutes <n> --concurrency <n> --reason "<why>"'));
+});
 export default new Command('tenant')
-    .description('Tenants: connecting new installations to Accounts, who left and deleting their data on request, and the one-time move into Accounts')
+    .description('Tenants: every installation of the App, connecting new ones to Accounts, who left and deleting their data on request, and the one-time move into Accounts')
     .addCommand(departuresCommand)
     .addCommand(purgeCommand)
     .addCommand(backfillCommand)
     .addCommand(unconnectedCommand)
-    .addCommand(connectCommand);
+    .addCommand(connectCommand)
+    .addCommand(installationsCommand);