@apex-actions/cli 0.74.0 → 0.76.0

package/dist/cli/reference.js

@@ -8,12 +8,21 @@
  * 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.
+ * for.** A customer's credential is an API token carrying the permissions its
+ * person chose (`resource:read|write`, write implying read), within one
+ * Account, their role there and the Account's token policy (control-plane
+ * ADR-0071). A token reaches the control plane's repository routes its grants
+ * cover, plus its own identity and tokens; every other route — the fleet, the
+ * operator's organisation, tenants, billing — answers it 403. So a command is
+ * `customer` exactly when every route it calls is a repository or self route in
+ * the control plane's `route-access.ts`, and `operator` otherwise, however
+ * customer-shaped it looks; a customer command with one operator subcommand or
+ * flag hides just that. Local commands need no control plane.
+ *
+ * **`permission` is the grant a token needs** — on the command, or per
+ * subcommand in `subcommandPermissions` (keyed by the path under the command,
+ * `subject set`) — read off the same table, so the site can say which
+ * `--permission` to ask for. A command that needs none has none.
  */
 /** The reference's sections, in the order a person meets them. */
 export const GROUPS = [
@@ -25,27 +34,35 @@ export const GROUPS = [
     { 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';
+/** Calls a control-plane route a customer token is refused on, whatever it holds. */
+const OPERATOR = '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.' },
+            { 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 --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',
         audience: 'customer',
         examples: [
-            { command: 'apex whoami', description: 'Who the CLI acts as, with which credential, and when it expires.' },
+            { command: 'apex whoami', description: "Who the CLI acts as, with which credential, and — for a token — what it may do and which Account it belongs to." },
             { command: 'apex whoami --json', description: 'The same, for a script.' },
         ],
     },
@@ -54,10 +71,22 @@ export const REFERENCE = {
         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 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 list --all', description: 'Every token you hold, expired and revoked ones included.' },
+            {
+                command: 'apex token edit 0b6f1c2e-9d4a-4f7e-8a31-5c2d9e7b1a40 --remove-permission secrets:write',
+                description: 'Narrow a token: applies at once, from the terminal.',
+            },
+            {
+                command: 'apex token edit 0b6f1c2e-9d4a-4f7e-8a31-5c2d9e7b1a40 --add-permission deployments:write',
+                description: 'Widen a token: the browser opens so you can approve it, within your Account\'s token policy.',
+            },
+            { command: 'apex token list --all', description: 'Every token you hold by Account, with its permissions — 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.' },
         ],
     },
@@ -86,11 +115,12 @@ export const REFERENCE = {
     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'],
+        // `scan` reads GitHub or a checkout; `coexist` changes the repository's settings on the control plane.
+        subcommandPermissions: { coexist: 'administration:write' },
         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.' },
+            { command: 'apex migrate coexist acme/web --on --add ci.yml', description: 'Run Apex beside GitHub Actions on one repository, starting with one workflow.' },
         ],
     },
     secret: {
@@ -98,6 +128,7 @@ export const REFERENCE = {
         audience: 'customer',
         // The organisation scope answers only for the operator's own organisation.
         operatorOptions: ['--org'],
+        subcommandPermissions: { list: 'secrets:read', set: 'secrets:write', delete: 'secrets:write' },
         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.' },
@@ -108,32 +139,173 @@ export const REFERENCE = {
         group: 'config',
         audience: 'customer',
         operatorOptions: ['--org'],
+        subcommandPermissions: { list: 'variables:read', set: 'variables:write', delete: 'variables:write' },
         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' },
+    // Runs and logs: a run's repository decides, by the token's `actions` grant.
+    logs: {
+        group: 'runs',
+        audience: 'customer',
+        permission: 'actions:read',
+        subcommandPermissions: { delete: 'actions:write' },
+        examples: [
+            { command: 'apex logs latest', description: 'The newest run you can see, every job, as it finished.' },
+            { command: 'apex logs 4812 --job test --follow', description: 'Follow one job of a run until it completes.' },
+        ],
+    },
+    search: {
+        group: 'runs',
+        audience: 'customer',
+        permission: 'actions:read',
+        examples: [{ command: 'apex search "ECONNRESET" --repo acme/web --conclusion failure', description: "Find a string in the last 30 days of a repository's failed jobs." }],
+    },
+    why: {
+        group: 'runs',
+        audience: 'customer',
+        permission: 'actions:read',
+        examples: [
+            { command: 'apex why 4812', description: 'Why a run happened: the event, the workflow and the rule that matched.' },
+            { command: 'apex why --delivery 7c1e0a52-3b9f-11ef-8e6b-2f4d1c9a0b77', description: 'Why a webhook produced no run at all.' },
+        ],
+    },
+    reproduce: {
+        group: 'runs',
+        audience: 'customer',
+        permission: 'actions:read',
+        examples: [{ command: 'apex reproduce 4812', description: 'Print the apex run command that replays a past run on this machine; secrets are named, never copied.' }],
+    },
+    timing: {
+        group: 'runs',
+        audience: 'customer',
+        permission: 'actions:read',
+        examples: [{ command: 'apex timing 4812 --steps 3', description: 'Where a run spent its time, with the three slowest steps of each job.' }],
+    },
+    tests: {
+        group: 'runs',
+        audience: 'customer',
+        permission: 'actions:read',
+        examples: [
+            { command: 'apex tests 4812', description: "A run's failing tests." },
+            { command: 'apex tests --flaky --repo acme/web', description: 'Tests that passed and failed at the same commit.' },
+        ],
+    },
+    rerun: {
+        group: 'runs',
+        audience: 'customer',
+        permission: 'actions:write',
+        examples: [
+            { command: 'apex rerun 4812 --failed', description: 'Re-run only what failed, and everything downstream of it.' },
+            { command: 'apex rerun 4812 --failed --resume', description: 'Resume each failed job at the step it failed at, where its snapshot survives.' },
+        ],
+    },
+    dispatch: {
+        group: 'runs',
+        audience: 'customer',
+        permission: 'actions:write',
+        examples: [{ command: 'apex dispatch deploy.yml --repo acme/web --ref main --input environment=staging', description: 'Trigger a workflow_dispatch run with a typed input.' }],
+    },
+    // Repository configuration: each resource its own grant.
+    environment: {
+        group: 'config',
+        audience: 'customer',
+        subcommandPermissions: { list: 'environments:read', set: 'environments:write', delete: 'environments:write' },
+        examples: [
+            { command: 'apex environment list acme/web', description: 'The environments a repository protects, and how.' },
+            { command: 'apex environment set acme/web production --reviewer user:octocat --branch-pattern main', description: 'Require a named reviewer, and deploy only from main.' },
+        ],
+    },
+    deployment: {
+        group: 'config',
+        audience: 'customer',
+        // Deciding also needs the person to be one of the environment's named reviewers.
+        subcommandPermissions: { list: 'deployments:read', approve: 'deployments:write', reject: 'deployments:write' },
+        examples: [
+            { command: 'apex deployment list', description: 'Deployments waiting for an approval, across the repositories you reach.' },
+            { command: 'apex deployment approve 91 --comment "staging looks good"', description: 'Approve one, with a comment recorded beside the decision.' },
+        ],
+    },
+    approval: {
+        group: 'config',
+        audience: 'customer',
+        subcommandPermissions: { list: 'approvals:read', approve: 'approvals:write', reject: 'approvals:write' },
+        examples: [
+            { command: 'apex approval list', description: 'Runs from forks waiting for somebody to approve them.' },
+            { command: 'apex approval approve 4812', description: 'Approve one: it runs without secrets, on a runner of its own.' },
+        ],
+    },
+    schedule: {
+        group: 'config',
+        audience: 'customer',
+        subcommandPermissions: { list: 'actions:read' },
+        examples: [{ command: 'apex schedule list acme/web', description: 'What a repository has scheduled, and when each fires next.' }],
+    },
+    notify: {
+        group: 'config',
+        audience: 'customer',
+        subcommandPermissions: {
+            list: 'notifications:read',
+            log: 'notifications:read',
+            add: 'notifications:write',
+            rm: 'notifications:write',
+            test: 'notifications:write',
+        },
+        examples: [
+            { command: 'apex notify add acme/web ops --kind slack --on broke,recovered', description: 'Tell a Slack channel when the default branch breaks and recovers; the URL is prompted for.' },
+            { command: 'apex notify log acme/web', description: "The last attempts to reach a repository's destinations." },
+        ],
+    },
+    actions: {
+        group: 'config',
+        audience: 'customer',
+        // An organisation's action policy is still the operator's.
+        operatorSubcommands: ['policy'],
+        subcommandPermissions: { list: 'actions:read', pin: 'administration:write' },
+        examples: [
+            { command: 'apex actions list acme/web', description: 'Every action a repository pulls in, least fixed first.' },
+            { command: 'apex actions pin acme/web --apply', description: 'Open a pull request pinning each action to the commit its version points at.' },
+        ],
+    },
+    oidc: {
+        group: 'config',
+        audience: 'customer',
+        subcommandPermissions: { subject: 'actions:read', 'subject set': 'actions:write' },
+        examples: [
+            { command: 'apex oidc discovery', description: 'The discovery document a cloud provider fetches to trust these tokens.' },
+            { command: 'apex oidc subject set acme/web --claim repo context job_workflow_ref', description: "Fold the calling workflow into a repository's subject claim." },
+        ],
+    },
+    cache: {
+        group: 'storage',
+        audience: 'customer',
+        subcommandPermissions: { list: 'actions:read', delete: 'actions:write' },
+        examples: [
+            { command: 'apex cache list acme/web', description: 'The caches a repository holds, most recently used first.' },
+            { command: 'apex cache delete acme/web 318', description: 'Drop one entry by id.' },
+        ],
+    },
+    artifact: {
+        group: 'storage',
+        audience: 'customer',
+        subcommandPermissions: { list: 'actions:read', download: 'actions:read', delete: 'actions:write' },
+        examples: [
+            { command: 'apex artifact list 4812', description: 'What a run produced.' },
+            { command: 'apex artifact download 4812 coverage -o coverage.zip', description: "Download one of a run's artifacts as a zip." },
+        ],
+    },
+    spend: {
+        group: 'billing',
+        audience: 'customer',
+        // With a token, one repository at a time; the fleet-wide report is the operator's.
+        permission: 'actions:read',
+        examples: [{ command: 'apex spend --repo acme/web --days 7', description: "A repository's last week of cost, next to what GitHub would have charged." }],
+    },
+    // The operator's: the fleet, the customer agreement's escalation path, and departed tenants' data.
+    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/spend/main.js

@@ -74,7 +74,7 @@ const handler = async (options) => {
 };
 export default new Command('spend')
     .description('Show what the fleet cost, next to what the same work would have cost on GitHub')
-    .option('--repo <owner/repo>', 'one repository (default: every repository)')
+    .option('--repo <owner/repo>', 'one repository — required with an API token (default for the operator: every repository)')
     .option('--days <n>', 'window in days, clamped to 1–365 (default: 30)')
     .option('--workflows <n>', `workflows to list (default: ${DEFAULT_ROWS})`)
     .option('--json', 'print the report as JSON')

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);

package/dist/cli/token/main.js

@@ -1,10 +1,11 @@
 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 { createToken, editToken, listTokens, revokeTokens } from '../../src/application/manage-tokens.js';
+import { MAX_TOKEN_DAYS, TOKENS_PAGE, TOKEN_RESOURCES, describeGrants, loopbackTimeoutHint, 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';
+import { approvalFlow, withFlowOptions } from '../login/device.js';
 /**
  * `apex token`: the person's API tokens from the terminal (control-plane
  * ADR-0064, amended 2026-09-27).
@@ -13,46 +14,84 @@ import { api, collect, usage } from '../secret/shared.js';
  * 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.
+ * A token carries the permissions asked for with `--permission` and belongs
+ * to one Account (control-plane ADR-0071).
+ * `edit` narrows a token at once with whichever credential the CLI has, and
+ * widens one only through the same browser approval.
  * `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 PERMISSION_HELP = `resource:read or resource:write (write implies read); resource is one of ${TOKEN_RESOURCES.join(', ')}`;
+/**
+ * The approval half `create` and a widening `edit` share — the loopback on this machine, or a device code
+ * (control-plane ADR-0075). Everything a person reads goes to stderr: stdout is the token's alone.
+ */
+const approvalDeps = (flags, what) => {
     const apiUrl = apiUrlFrom();
-    const outcome = await createToken({
+    const chosen = approvalFlow(flags, apiUrl, (line) => console.error(line));
+    if ('problem' in chosen)
+        return chosen;
+    return {
         pkce: newPkcePair,
         listen: (state) => listenForCallback(state),
-        openBrowser: opts.browser ? (url) => openInBrowser(url) : undefined,
+        openBrowser: (url) => openInBrowser(url),
         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(`Opening the browser to approve ${what}. If it does not open, visit:`);
             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 });
+        flow: chosen.flow,
+        device: chosen.device,
+    };
+};
+const refused = (message) => {
+    console.error(chalk.red(message));
+    process.exitCode = 1;
+};
+const createCommand = withFlowOptions(new Command('create')
+    .description('Create an API token for a script or CI system, approved in the browser — here, or on any device with a code; 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('--permission <permission>', `what the token may do, repeatable and at least one: ${PERMISSION_HELP}`, collect, [])
+    .option('--account <id>', 'the Account the token belongs to — needed when you belong to more than one')
+    .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 reach in the Account', collect, [])
+    .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 deps = approvalDeps(opts, 'this token');
+    if ('problem' in deps) {
+        usage(deps.problem);
+        return;
+    }
+    const outcome = await createToken(deps, {
+        name,
+        days,
+        repos: opts.repo,
+        permissions: opts.permission,
+        accountId: opts.account,
+    });
     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));
+                console.log(JSON.stringify({
+                    token: outcome.token,
+                    id: outcome.id,
+                    name: outcome.name,
+                    login: outcome.login,
+                    expiresAt: outcome.expiresAt,
+                    repos: outcome.repos ?? null,
+                    permissions: outcome.permissions ?? [],
+                    accountId: outcome.accountId ?? null,
+                }, null, 2));
             }
             else {
                 console.log(outcome.token);
             }
-            const reach = outcome.repos === undefined || outcome.repos.length === 0 ? 'every repository you administer' : outcome.repos.join(', ');
+            const reach = outcome.repos === undefined || outcome.repos.length === 0 ? 'every repository you reach' : outcome.repos.join(', ');
             console.error(`${chalk.green('✔')} created "${outcome.name}" for ${outcome.login} — ${reach}; expires ${outcome.expiresAt}`);
+            console.error(`  permissions: ${describeGrants(outcome.permissions)}${outcome.accountId === undefined ? '' : ` · Account ${outcome.accountId}`}`);
             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;
         }
@@ -69,17 +108,92 @@ const createCommand = new Command('create')
             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');
+            refused(loopbackTimeoutHint('apex token create'));
+            return;
+        case 'expired':
+            refused('the code expired before anyone approved it; run apex token create again for a new one');
             return;
         case 'refused':
             refused(outcome.detail);
             return;
     }
 });
-const reachOf = (t) => (t.repos === undefined || t.repos.length === 0 ? 'all administered' : t.repos.join(', '));
+const reachOf = (t) => (t.repos === undefined || t.repos.length === 0 ? 'all' : t.repos.join(', '));
 const day = (iso) => (iso === undefined ? '—' : iso.slice(0, 10));
+const editCommand = withFlowOptions(new Command('edit')
+    .description('Change what a token may do or which repositories it reaches; narrowing applies at once, widening is approved in the browser — here, or on any device with a code')
+    .argument('<id>', 'the token id, from apex token list')
+    .option('--permission <permission>', `the token's whole new set of permissions, repeatable: ${PERMISSION_HELP}`, collect, [])
+    .option('--add-permission <permission>', 'add one permission to what the token holds (repeatable)', collect, [])
+    .option('--remove-permission <permission>', 'take one permission away (repeatable)', collect, [])
+    .option('--repo <owner/repo>', "the token's new list of repositories (repeatable, up to 100)", collect, [])
+    .option('--all-repos', 'let the token reach every repository you reach in its Account')
+    .option('--json', 'print the edited token as JSON')).action(async (id, opts) => {
+    if (opts.allRepos === true && opts.repo.length > 0) {
+        usage('pass --repo or --all-repos, not both');
+        return;
+    }
+    const deps = approvalDeps(opts, 'widening this token');
+    if ('problem' in deps) {
+        usage(deps.problem);
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await editToken(client, deps, id, {
+        ...(opts.permission.length > 0 ? { permissions: opts.permission } : {}),
+        add: opts.addPermission,
+        remove: opts.removePermission,
+        ...(opts.allRepos === true ? { repos: 'all' } : opts.repo.length > 0 ? { repos: opts.repo } : {}),
+    });
+    switch (outcome.kind) {
+        case 'edited':
+        case 'unchanged': {
+            const t = outcome.token;
+            if (opts.json === true) {
+                console.log(JSON.stringify({ token: t, changed: outcome.kind === 'edited', ...(outcome.kind === 'edited' ? { via: outcome.via } : {}) }, null, 2));
+                return;
+            }
+            if (outcome.kind === 'unchanged')
+                console.log(chalk.yellow(`"${t.name}" already holds that — nothing changed`));
+            else
+                console.log(`${chalk.green('✔')} edited "${t.name}"${outcome.via === 'browser' ? ' — the widening was approved in the browser' : ''}`);
+            console.log(`  permissions   ${describeGrants(t.permissions)}`);
+            console.log(`  repositories  ${reachOf(t)}`);
+            if (t.accountId !== undefined)
+                console.log(`  account       ${t.accountId}`);
+            return;
+        }
+        case 'invalid':
+            usage(outcome.detail);
+            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 '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 edit again');
+            return;
+        case 'malformed':
+            refused('the browser came back without a code; run apex token edit again');
+            return;
+        case 'timeout':
+            refused(loopbackTimeoutHint('apex token edit'));
+            return;
+        case 'expired':
+            refused('the code expired before anyone approved the widening; run apex token edit again for a new one');
+            return;
+        case 'refused':
+            refused(outcome.detail);
+            return;
+    }
+});
 const listCommand = new Command('list')
-    .description('Your API tokens — names and last four characters, never the tokens')
+    .description('Your API tokens by Account, with what each may do — names and last four characters, never the tokens')
     .option('--all', 'include expired and revoked tokens')
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
@@ -99,23 +213,32 @@ const listCommand = new Command('list')
         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) => [
+    const header = ['  NAME', 'ID', 'LAST 4', 'SOURCE', 'PERMISSIONS', 'REPOSITORIES', 'EXPIRES', 'LAST USED', 'STATE'];
+    const rowOf = (t) => [
         `${t.current === true ? '* ' : '  '}${t.name}`,
         t.id,
         `…${t.last4}`,
         t.source,
+        describeGrants(t.permissions),
         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 rows = outcome.tokens.map(rowOf);
     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));
+    // One section per Account: a token belongs to one, and reaches only that Account's repositories.
+    const accounts = [...new Set(outcome.tokens.map((t) => t.accountId ?? ''))].sort((a, b) => (a === '' ? 1 : b === '' ? -1 : a.localeCompare(b)));
+    accounts.forEach((account, i) => {
+        if (i > 0)
+            console.log('');
+        console.log(chalk.bold(account === '' ? 'No Account — these tokens reach nothing; create a new one' : `Account ${account}`));
+        console.log(chalk.dim(line(header)));
+        for (const t of outcome.tokens)
+            if ((t.accountId ?? '') === account)
+                console.log(line(rowOf(t)));
+    });
     if (outcome.tokens.some((t) => t.current === true))
         console.log(chalk.dim('* the token this CLI is using'));
     if (outcome.hidden > 0)
@@ -151,7 +274,8 @@ const revokeCommand = new Command('revoke')
     }
 });
 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}`)
+    .description(`API tokens for scripts and CI: create one with the permissions it needs (approved in the browser), edit, list or revoke yours. Also on the dashboard at ${TOKENS_PAGE}`)
     .addCommand(createCommand)
+    .addCommand(editCommand)
     .addCommand(listCommand)
     .addCommand(revokeCommand);