cli

apex developer and operator CLI (TypeScript, commander).

Part of the Apex Actions superproject. Conventions, architecture, and agent context live in the context repository.

Commands

| Command | Reaches | Needs | | --- | --- | --- | | apex run | the runner binary, locally | apex-runner on PATH | | apex validate | the engine binary, locally | apex-engine on PATH | | apex migrate scan | the engine binary + the GitHub REST API | apex-engine on PATH; GITHUB_TOKEN unless --path | | apex logs | the control-plane REST API | a customer token with actions:read (logs delete: actions:write), or the machine token | | apex dispatch | the control-plane REST API | a customer token with actions:write, or the machine token | | apex login · logout · whoami | the browser and the control-plane REST API | nothing — login mints the credential | | apex token create | the browser and the control-plane REST API | a person signed in to the dashboard, who approves it | | apex token edit | the control-plane REST API; the browser to widen | a customer token to narrow; a person signed in to the dashboard to widen | | apex token list · revoke | the control-plane REST API | a customer token (APEX_TOKEN or apex login) | | apex secret · apex variable | the control-plane REST API | a customer token with secrets:* / variables:* (APEX_TOKEN or apex login) | | apex login --console · logout --console | the Admin Console in the browser, and the control-plane REST API | an operator signed in to the Admin Console, who approves it | | apex grant list · apex tenant installations | the control-plane admin API | the operator token (apex login --console), or the machine token | | apex grant create · update · revoke | the control-plane admin API | the operator token (apex login --console) — never the machine token (control-plane ADR-0056, ADR-0079) |

Every other customer command in cli/reference.ts names the permission it needs; the public reference shows it.

Generated reference: docs/feature-docs/cli-commands.md (pnpm docs:cli from packages/release), and the structured one the public site renders, docs/feature-docs/cli-reference.json (pnpm docs:reference; customer commands only, classified in cli/reference.ts).

export APEX_API_URL=https://apex.example
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
apex logs '#42' --job test                 # one job, clean enough to pipe

apex migrate scan answers "will my workflows run" before anything has moved. Every verdict comes out of the engine's conformance corpus with the fixture that proves it (ADR-0002, engine ADR-0013) — nothing here holds a second opinion about compatibility. It imports secret and variable names and never values, and --path scans a checkout on this machine with no token and no network:

apex migrate scan --path .                      # this repository, no credentials
apex migrate scan acme --repo acme/api --json   # one repository of an organization

Credentials

The CLI resolves one credential, in this order (control-plane ADR-0064, amended by ADR-0005) — the environment outranks the file:

1. APEX_TOKEN — a token minted on the dashboard (/settings/tokens), for CI and scripts;
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;
4. otherwise the command stops with exit 2, naming APEX_TOKEN and apex login.

Operator commands — apex grant and apex tenant installations — look first for the operator token apex login --console saved in $XDG_CONFIG_HOME/apex/console-credentials (same mode rules), when it is unexpired and was minted by the control plane APEX_API_URL names, and otherwise use the order above (control-plane ADR-0079). The operator token is approved on the Admin Console (APEX_CONSOLE_URL, or the API's app. host read as admin.) by an operator, by loopback only; it lives a week at most and reaches only the grant routes and the installation list, and every grant it writes names its operator. The machine token can list grants and is refused every write. apex logout --console revokes and forgets it.

APEX_API_URL selects the control plane (default https://app.apexactions.com); a saved login is only ever sent to the control plane that issued it. apex login opens the consent page on the web app — APEX_WEB_URL, or the API's origin — and listens on 127.0.0.1 for the loopback callback (RFC 8252, PKCE); once the code is redeemed it hands the tab back to the web app's bare /cli/done page (control-plane ADR-0075). 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.

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
apex secret list --repo acme/api --json                      # names only

A pipeline gets its own token. It is approved in the browser like a login, printed once to stdout, and never saved (control-plane ADR-0064: a token never mints a token):

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

apex secret set never takes the value from the command line — argv is visible in ps and saved in shell history (BUG-0157) — so --value is refused with exit 2. Exit codes: 0 done · 1 the API refused · 2 usage or configuration · 3 not found on delete.

Layout

• cli/<command>/main.ts — one commander leaf per command (§7)
• src/domain/ — pure decisions: run and job selection, input parsing, exit codes
• src/application/ — use cases over ports
• src/infrastructure/ — adapters: the engine and runner binaries, the REST API
• docs/ — general docs (*.md), adr/, feature-docs/, run-book/
• VERSION — lockstep version, managed by the release library; do not edit by hand

Licence

@apex-actions/cli is proprietary software, licensed under the Apex Actions Software Licence — see LICENSE. The hosted service it talks to is governed by the terms of service.