@apex-actions/cli 0.74.0 → 0.76.0

package/README.md

@@ -11,12 +11,18 @@ 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 | the operator token (`APEX_ADMIN_TOKEN`) |
-| `apex dispatch` | the control-plane REST API | the operator token (`APEX_ADMIN_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 (`APEX_TOKEN` or `apex login`), repository admin |
+| `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.
 
 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`;
@@ -24,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
@@ -43,26 +49,53 @@ apex migrate scan acme --repo acme/api --json   # one repository of an organizat
 
 ### Credentials
 
-The CLI resolves one credential, in this order (control-plane ADR-0064):
+The CLI resolves one credential, in this order (control-plane ADR-0064, amended by
+[ADR-0005](docs/adr/0005-an-exported-token-outranks-a-saved-login.md)) — **the environment outranks
+the file**:
 
 1. `APEX_TOKEN` — a token minted on the dashboard (`/settings/tokens`), for CI and scripts;
-2. the token `apex login` saved in `$XDG_CONFIG_HOME/apex/credentials` (default `~/.config`),
+2. `APEX_ADMIN_TOKEN` — the operator's machine token, unchanged: unscoped, so treat it as a root
+   credential. An exported variable is the deliberate choice, as `GH_TOKEN` outranks `gh`'s stored
+   login; a saved login used to win, so an operator shell acted as whichever customer had last run
+   `apex login` on the machine;
+3. the token `apex login` saved in `$XDG_CONFIG_HOME/apex/credentials` (default `~/.config`),
    mode `0600` in a `0700` directory — a file readable by group or others is **refused**, as `ssh`
    refuses a private key;
-3. `APEX_ADMIN_TOKEN` — the operator's machine token, unchanged: unscoped, so treat it as a root
-   credential;
 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). A customer token's scope is repository secrets and variables plus `/me`; every
-other command answers with the server's 403. `apex logout` revokes the saved token on the server,
+(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). 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
+defaults for the person's role (the Owner's: everything), in the Account `--account` names when there is more than
+one. A route it lacks the grant for answers 403 `this token needs <permission>`, which the CLI completes with the
+`apex token edit <id> --add-permission <permission>` that would add it. `apex whoami`
+names the credential in use, where it was found, and any other credential present that it
+outranked. `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
+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
@@ -73,8 +106,11 @@ A pipeline gets its own token. It is approved in the browser like a login, print
 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 create ci-deploy --permission actions:write --permission secrets:write \
+  --repo acme/api --expires-in-days 30                             # token on stdout, details on stderr
+apex token edit <id> --remove-permission secrets:write             # narrowing: applies at once
+apex token edit <id> --add-permission deployments:write            # widening: approved in the browser
+apex token list                                                    # by Account, with grants; * marks the one in use
 apex token revoke 0b6f1c2e-9d4a-4f7e-8a31-5c2d9e7b1a40              # or --all
 ```
 

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,66 @@
 import { hostname } from 'node:os';
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { login } from '../../src/application/authenticate.js';
-import { TOKENS_PAGE, webBaseFor } from '../../src/domain/credentials.js';
-import { 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')
-    .option('--no-browser', 'print the URL to open instead of opening a browser')
-    .action(async (opts) => {
+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('--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,
             webBase,
             name: hostname().slice(0, 100) || 'apex CLI',
+            accountId: opts.account,
         });
     }
     catch (err) {
@@ -43,31 +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}`);
-            console.log(chalk.dim(`Saved to ${outcome.location}. Revoke it any time at ${webBase}${TOKENS_PAGE}.`));
-            if (process.env[TOKEN_ENV])
-                console.log(chalk.yellow(`${TOKEN_ENV} is set in this shell and is used before the saved 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; 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 { 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 { FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFrom, credentialsPat
  * 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,6 +44,8 @@ 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;
     }
-    if (process.env[TOKEN_ENV])
-        console.log(chalk.yellow(`${TOKEN_ENV} is still set in this shell, and the CLI still uses it.`));
+    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)