cli

apex developer and operator CLI (TypeScript, commander).

A workspace of the Apex Actions repository. What it is inside: docs/architecture/components/cli.md; the conventions: docs/conventions/.

Commands

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

Generated reference: docs/features/cli-commands.md (pnpm docs:cli from packages/tooling), and the structured one the public site renders, apps/cli/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 (cli 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 (api 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 (api 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 (api 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 (api 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 (api 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
• Documentation is the root's: decisions in docs/adrs/cli/, the rest by category in docs/ (TASK-0526)
• VERSION — the release version, which version:sync writes from the root (ADR-0048); never edited 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.