@apex-actions/cli 0.73.1 → 0.75.0

package/README.md

@@ -11,12 +11,15 @@ 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 operator token |
+| `apex dispatch` | the control-plane REST API | a customer token with `actions:write`, or the operator 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`) |
+
+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`;
@@ -43,21 +46,33 @@ 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`.
 
 `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). 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.
 
@@ -73,8 +88,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/environment/main.js

@@ -59,7 +59,7 @@ const setCommand = new Command('set')
     .argument('<repository>', 'owner/repo')
     .argument('<name>', 'environment name, as the workflow spells it')
     .option('--wait-timer <minutes>', 'delay before the job may start; 0 removes it', (v) => Number(v))
-    .option('--reviewer <who...>', 'user:<login>, team:<org/slug>, or a bare login (a user)')
+    .option('--reviewer <who...>', 'user:<login>, role:<owner|account_admin|billing|member|viewer>, or a bare login (a user)')
     .option('--branch-pattern <glob...>', 'refs permitted to deploy here (main, releases/*, v?.0)')
     .option('--prevent-self-review', 'refuse an approval from whoever triggered the run')
     .option('--allow-self-review', 'permit it (the default)')
@@ -78,7 +78,7 @@ const setCommand = new Command('set')
         for (const raw of opts.reviewer) {
             const parsed = parseReviewer(raw);
             if (!parsed) {
-                console.error(chalk.red(`expected user:<login>, team:<org/slug> or a bare login, got ${JSON.stringify(raw)}`));
+                console.error(chalk.red(`expected user:<login>, role:<owner|account_admin|billing|member|viewer> or a bare login, got ${JSON.stringify(raw)}`));
                 process.exitCode = 2;
                 return;
             }

package/dist/cli/login/main.js

@@ -2,8 +2,8 @@ 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 { 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 { HttpLoginExchange, listenForCallback, newPkcePair, openInBrowser } from '../../src/infrastructure/loopback-login.js';
 /**
  * `apex login`: sign the CLI in with the browser a person already uses
@@ -12,9 +12,14 @@ import { HttpLoginExchange, listenForCallback, newPkcePair, openInBrowser } from
  *
  * 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.
+ *
+ * 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).
  */
 export default new Command('login')
-    .description('Sign the CLI in through the browser; the token is saved for this user only')
+    .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")
+    .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) => {
     const apiUrl = apiUrlFrom();
@@ -36,6 +41,7 @@ export default new Command('login')
             apiUrl,
             webBase,
             name: hostname().slice(0, 100) || 'apex CLI',
+            accountId: opts.account,
         });
     }
     catch (err) {
@@ -46,9 +52,15 @@ export default new Command('login')
     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}.`));
-            if (process.env[TOKEN_ENV])
-                console.log(chalk.yellow(`${TOKEN_ENV} is set in this shell and is used before the saved login.`));
+            // 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}`));
@@ -63,7 +75,7 @@ export default new Command('login')
             process.exitCode = 1;
             return;
         case 'timeout':
-            console.error(chalk.red('no approval arrived within 5 minutes; run `apex login` again'));
+            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;
             return;
         case 'refused':

package/dist/cli/logout/main.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import { logout } from '../../src/application/authenticate.js';
 import { TOKENS_PAGE, 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, FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFrom, credentialsPath } from '../../src/infrastructure/credentials.js';
 /**
  * `apex logout`: revoke the token `apex login` saved, then forget it.
  *
@@ -38,6 +38,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 [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/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,14 +34,15 @@ 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', 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.' },
         ],
     },
@@ -45,7 +55,7 @@ export const REFERENCE = {
         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 +64,18 @@ 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 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, expired and revoked ones included.' },
+            { 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 +104,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 +117,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 +128,171 @@ 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 },
 };

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

@@ -1,8 +1,8 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { listDepartures, purgeDeparture } from '../../src/application/manage-departures.js';
-import { backfillAccounts } from '../../src/application/manage-accounts.js';
-import { backfillLines } from '../../src/domain/accounts.js';
+import { backfillAccounts, connectInstallation, listUnconnected } from '../../src/application/manage-accounts.js';
+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';
 /** Build the API client, or explain what is missing and stop. */
@@ -103,8 +103,64 @@ const backfillCommand = new Command('backfill')
     if (!outcome.value.applied)
         console.log(chalk.yellow('\nNothing was changed. Review the above, then re-run with --apply.'));
 });
+const unconnectedCommand = new Command('unconnected')
+    .description('Installations no Apex Account owns, the longest-waiting first — their people are refused until connected (decisions-log O20)')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listUnconnected(client);
+    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('every installation is connected to an Account'));
+        return;
+    }
+    const now = new Date();
+    for (const i of outcome.value)
+        console.log(`  ${unconnectedLine(i, now)}`);
+    console.log(chalk.dim('\nConnect one with: apex tenant connect <installationId> --owner <github-login> [--name <Account name>]'));
+});
+const connectCommand = new Command('connect')
+    .description('Connect one installation to the Account --owner owns, creating it with them its Owner when they own none (decisions-log O20)')
+    .argument('<installationId>', 'the installation to connect (see: apex tenant unconnected)')
+    .requiredOption('--owner <login>', 'the GitHub login of the Account’s Owner; they must have signed in once')
+    .option('--name <name>', 'the Account’s name — required when the Owner owns no Account yet')
+    .option('--json', 'machine-readable output')
+    .action(async (raw, opts) => {
+    const installationId = Number(raw);
+    if (!Number.isSafeInteger(installationId) || installationId <= 0) {
+        console.error(chalk.red(`expected a positive installation id, got ${JSON.stringify(raw)}`));
+        process.exitCode = 2;
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await connectInstallation(client, { installationId, ownerLogin: opts.owner, name: opts.name });
+    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;
+    }
+    console.log(`${chalk.green('✔')} ${connectLine(outcome.value)}`);
+});
 export default new Command('tenant')
-    .description('Tenants: who left and deleting their data on request, and the one-time move into Accounts')
+    .description('Tenants: connecting new installations to Accounts, who left and deleting their data on request, and the one-time move into Accounts')
     .addCommand(departuresCommand)
     .addCommand(purgeCommand)
-    .addCommand(backfillCommand);
+    .addCommand(backfillCommand)
+    .addCommand(unconnectedCommand)
+    .addCommand(connectCommand);