@apex-actions/cli 0.67.0

package/LICENSE

@@ -0,0 +1,20 @@
+Apex Actions Software Licence
+
+Copyright (c) 2026 Apex Actions. All rights reserved.
+
+This software is proprietary. It is licensed, not sold, under the Apex Actions
+Software Licence, whose current text is published at
+
+    https://apexactions.com/legal/software-licence/
+
+and is incorporated here by reference. In short: you may install and run it for
+use with the Apex Actions hosted service, or with a deployment of the service
+that a written agreement entitles you to operate; you may not redistribute,
+modify, reverse engineer, or use it to build a competing service. Every right
+not granted there is reserved.
+
+Third-party components are included under their own licences, which this
+licence does not restrict; their notices accompany the software.
+
+The hosted service itself is governed by the Terms of Service at
+https://apexactions.com/legal/terms/, not by this licence.

package/README.md

@@ -0,0 +1,84 @@
+# 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 | the operator token (`APEX_ADMIN_TOKEN`) |
+| `apex dispatch` | the control-plane REST API | the operator token (`APEX_ADMIN_TOKEN`) |
+| `apex login` · `logout` · `whoami` | the browser and the control-plane REST API | nothing — `login` mints the credential |
+| `apex secret` · `apex variable` | the control-plane REST API | a customer token (`APEX_TOKEN` or `apex login`), repository admin |
+
+Generated reference: `docs/feature-docs/cli-commands.md` (`pnpm docs:cli`).
+
+```bash
+export APEX_API_URL=https://apex.example
+export APEX_ADMIN_TOKEN=…                       # the operator 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:
+
+```bash
+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):
+
+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`),
+   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` deletes the file only: a token cannot
+revoke itself, so revoke it on the dashboard. No command prints a token.
+
+```bash
+apex login                                                   # once per machine
+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
+```
+
+`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](https://apexactions.com/legal/software-licence/) — see `LICENSE`.
+The hosted service it talks to is governed by the [terms of service](https://apexactions.com/legal/terms/).