Reference

CLI reference

Every command the apex CLI offers, with its options — generated from the CLI itself, so it describes the binary you installed rather than the one somebody documented.

apex

Usage: apex [options] [command] Apex Actions — developer and operator CLI Options: -V, --version output the version number -h, --help display help for command Commands: run [options] [workflow] Run a workflow locally with the same engine and executor as the service (wraps apex-runner --local) validate [options] [files...] Validate workflow files against the engine (defaults to .github/workflows/*.yml) migrate Plan a migration from GitHub Actions: what runs, what does not, and what has to be re-entered logs [options] [run] Stream or fetch logs for a run or job search [options] [query] Search a repository’s log text across runs why [options] [run] Explain why a run happened — or, with --delivery, why a webhook produced no run at all reproduce [options] [run] Print the `apex run` invocation that reproduces a past run locally (secrets by name only) timing [options] [run] Show where a run spent its time, and which steps got slower than usual tests [options] [run] Show a run’s test results, or a repository’s unreliable tests with --flaky rerun [options] [run] Re-run a completed run — all of it, only what failed, or one job — optionally resuming from the step that failed spend [options] Show what the fleet cost, next to what the same work would have cost on GitHub dispatch [options] <workflow> Trigger workflow_dispatch with typed inputs runner Runners: attach this machine, list what is registered, mint tokens, deregister, read the fleet’s past cache Caches: what a repository holds, and dropping an entry artifact Artifacts: what a run produced, getting it out, and dropping one environment Environments: the protection rules a workflow can only name deployment Deployments: what is waiting for an approval, and giving one approval Runs from forks: what is waiting, and deciding it (ADR-0024) schedule Schedules: what `on: schedule` will fire, and when oidc OIDC: what this issuer publishes, and what a token says it is actions The action supply chain: what a repository pulls in, the policy over it, and pinning terms The customer agreement: who owes an acceptance of the terms in force, and the escalation path notify Notification routing: where a repository’s outcome changes are sent lsp Run the workflow language server on stdio, for an editor to start as a child process help [command] display help for command

apex run

Usage: apex run [options] [workflow] Run a workflow locally with the same engine and executor as the service (wraps apex-runner --local) Arguments: workflow workflow file to run (default: the only file in .github/workflows/) Options: --job <id> run only this job id (its needs are assumed satisfied) --event <name> event to plan against (default: push) --payload <file> JSON file with the event payload --secret <KEY=value> secret (repeatable); GITHUB_TOKEN reaches the github context (default: []) --var <KEY=value> repository variable (repeatable) (default: []) --input <key=value> workflow_dispatch input (repeatable) (default: []) --changed-file <path> changed file for paths filters (repeatable) (default: []) --image <image> default job container image --json print the run result as JSON on stdout -h, --help display help for command

apex validate

Usage: apex validate [options] [files...] Validate workflow files against the engine (defaults to .github/workflows/*.yml) Arguments: files workflow files to validate ("-" reads stdin) Options: --json print diagnostics as JSON -h, --help display help for command

apex migrate

Usage: apex migrate [options] [command] Plan a migration from GitHub Actions: what runs, what does not, and what has to be re-entered Options: -h, --help display help for command Commands: scan [options] [org] Report what an organization's workflows do on Apex Actions, and what each verdict is proved by coexist [options] <repository> Run Apex beside GitHub Actions on one repository, opting workflows in one at a time help [command] display help for command

apex migrate scan

Usage: apex migrate scan [options] [org] Report what an organization's workflows do on Apex Actions, and what each verdict is proved by Arguments: org GitHub organization to scan Options: --repo <owner/repo> limit to this repository (repeatable) (default: []) --path <dir> scan a checkout on this machine instead of the GitHub API --no-secrets skip the secret and variable name import --uses <n> how many places to list per feature (default: 3) --json print the scan as JSON -h, --help display help for command

apex migrate coexist

Usage: apex migrate coexist [options] <repository> Run Apex beside GitHub Actions on one repository, opting workflows in one at a time Arguments: repository owner/repo Options: --on turn coexistence on: Apex plans only opted-in workflows here --off turn it off: Apex is this repository’s CI and runs everything not disabled --add <workflow...> opt a workflow in, by path or file name --remove <workflow...> opt a workflow back out --diff <sha> compare both platforms’ outcomes for one commit -h, --help display help for command

apex logs

Usage: apex logs [options] [run] Stream or fetch logs for a run or job Arguments: run run id, #number, or "latest" (default: "latest") Options: --repo <owner/repo> limit the run search to one repository --job <name> one job by id, name, or name prefix (default: every job) --follow keep reading until the run completes --summary print what the log says about the tests it ran, instead of the log --json print the run and its logs as JSON -h, --help display help for command

apex search

Usage: apex search [options] [query] Search a repository’s log text across runs Arguments: query terms, "a phrase" to keep words together, -term to exclude; all required terms must be on the same line Options: -e, --query <query> the query, for one that starts with "-" — an argument beginning with a dash is read as an option --repo <owner/repo> the repository to search (required) --workflow <path> one workflow file --branch <name> one branch, written as a name or a full ref --conclusion <state> jobs that ended this way, e.g. failure --job <name> one job by name or matrix key --case match case (default: fold it) --days <n> window in days, clamped to 1–365 (default: 30) --limit <n> jobs whose logs are read, newest first (default: 200) --json print the report as JSON -h, --help display help for command

apex why

Usage: apex why [options] [run] Explain why a run happened — or, with --delivery, why a webhook produced no run at all Arguments: run run id, #number, or "latest" (default: "latest") Options: --repo <owner/repo> limit the run search to one repository --delivery <id> explain a webhook delivery instead of a run --json print the explanation as JSON -h, --help display help for command

apex reproduce

Usage: apex reproduce [options] [run] Print the `apex run` invocation that reproduces a past run locally (secrets by name only) Arguments: run run id, #number, or "latest" (default: "latest") Options: --repo <owner/repo> limit the run search to one repository --job <key> reproduce one matrix leg by its key, rather than the whole workflow --no-write print the command without writing the event payload file it refers to --json print the recipe as JSON -h, --help display help for command

apex timing

Usage: apex timing [options] [run] Show where a run spent its time, and which steps got slower than usual Arguments: run run id, #number, or "latest" (default: "latest") Options: --repo <owner/repo> limit the run search to one repository --steps <n> slowest steps to show per job (default: 5) --json print the timings as JSON -h, --help display help for command

apex tests

Usage: apex tests [options] [run] Show a run’s test results, or a repository’s unreliable tests with --flaky Arguments: run run id, #number, or "latest" (default: "latest") Options: --repo <owner/repo> limit the run search to one repository; required with --flaky --flaky list the repository’s tests that passed and failed at the same commit --all list every test, not only the failures --json print the results as JSON -h, --help display help for command

apex rerun

Usage: apex rerun [options] [run] Re-run a completed run — all of it, only what failed, or one job — optionally resuming from the step that failed Arguments: run run id, #number, or "latest" (default: "latest") Options: --repo <owner/repo> limit the run search to one repository --failed only the jobs that did not succeed, plus everything downstream of one --job <id> one engine job id and its dependents (matrix legs re-run as a unit, like GitHub) --resume start each job at the step it failed at, where a snapshot of that failure survives --debug enable step debug logging for the new attempt --json print the result as JSON -h, --help display help for command

apex spend

Usage: apex spend [options] Show what the fleet cost, next to what the same work would have cost on GitHub Options: --repo <owner/repo> one repository (default: every repository) --days <n> window in days, clamped to 1–365 (default: 30) --workflows <n> workflows to list (default: 10) --json print the report as JSON -h, --help display help for command

apex dispatch

Usage: apex dispatch [options] <workflow> Trigger workflow_dispatch with typed inputs Arguments: workflow workflow file path or name, e.g. .github/workflows/deploy.yml Options: --repo <owner/repo> repository to dispatch in --ref <ref> branch or tag to run against, as on GitHub (a commit SHA is refused) (default: "main") --input <name=value...> workflow_dispatch input, repeatable -h, --help display help for command

apex runner

Usage: apex runner [options] [command] Runners: attach this machine, list what is registered, mint tokens, deregister, read the fleet’s past Options: -h, --help display help for command Commands: list [options] Registered runners, and the work waiting for them history [options] How big the fleet was, and when it was at zero, over a window that has passed token [options] Mint a runner registration token (single-use by default) register [options] Attach this machine as a self-hosted runner and start leasing work remove <id> Deregister a runner by id, revoking its credential help [command] display help for command

apex runner list

Usage: apex runner list [options] Registered runners, and the work waiting for them Options: --json machine-readable output -h, --help display help for command

apex runner history

Usage: apex runner history [options] How big the fleet was, and when it was at zero, over a window that has passed Options: --since <duration> how far back to look: 24h, 90m, 2d (default: "24h") --until <iso> end of the window (default: now) --json machine-readable output -h, --help display help for command

apex runner token

Usage: apex runner token [options] Mint a runner registration token (single-use by default) Options: --uses <n> registrations this token may grant, 1–64 (default: "1") -h, --help display help for command

apex runner register

Usage: apex runner register [options] Attach this machine as a self-hosted runner and start leasing work Options: --labels <labels> comma-separated labels, e.g. self-hosted,linux,gpu --server <host:port> runner endpoint (APEX_RUNNER_SERVER) --name <name> display name (default: this hostname) --work-dir <path> scratch root for job workspaces --idle-timeout <duration> stop after this long with no job, e.g. 30m (default: never) --ephemeral take one job, then deregister (default: false) -h, --help display help for command

apex runner remove

Usage: apex runner remove [options] <id> Deregister a runner by id, revoking its credential Arguments: id runner id (apex runner list prints them) Options: -h, --help display help for command

apex cache

Usage: apex cache [options] [command] Caches: what a repository holds, and dropping an entry Options: -h, --help display help for command Commands: list [options] <repository> Caches a repository holds, most recently used first delete <repository> <id> Delete one cache entry by id help [command] display help for command

apex cache list

Usage: apex cache list [options] <repository> Caches a repository holds, most recently used first Arguments: repository owner/repo Options: --json machine-readable output -h, --help display help for command

apex cache delete

Usage: apex cache delete [options] <repository> <id> Delete one cache entry by id Arguments: repository owner/repo id cache id (apex cache list prints them) Options: -h, --help display help for command

apex artifact

Usage: apex artifact [options] [command] Artifacts: what a run produced, getting it out, and dropping one Options: -h, --help display help for command Commands: list [options] <target> Artifacts a run or a repository holds, newest first download [options] <run> [name] Download one artifact of a run as a zip delete <run> <id> Delete one artifact by id help [command] display help for command

apex artifact list

Usage: apex artifact list [options] <target> Artifacts a run or a repository holds, newest first Arguments: target run id, or owner/repo Options: --json machine-readable output -h, --help display help for command

apex artifact download

Usage: apex artifact download [options] <run> [name] Download one artifact of a run as a zip Arguments: run run id name artifact name (optional when the run produced exactly one) Options: -o, --output <path> where to write the zip (default: <name>.zip here) -h, --help display help for command

apex artifact delete

Usage: apex artifact delete [options] <run> <id> Delete one artifact by id Arguments: run run id id artifact id (apex artifact list prints them) Options: -h, --help display help for command

apex environment

Usage: apex environment [options] [command] Environments: the protection rules a workflow can only name Options: -h, --help display help for command Commands: list [options] <repository> Environments this repository protects, and how set [options] <repository> <name> Create or update an environment protection rule (repository admin) delete <repository> <name> Remove an environment protection rule (repository admin) help [command] display help for command

apex environment list

Usage: apex environment list [options] <repository> Environments this repository protects, and how Arguments: repository owner/repo Options: --json machine-readable output -h, --help display help for command

apex environment set

Usage: apex environment set [options] <repository> <name> Create or update an environment protection rule (repository admin) Arguments: repository owner/repo name environment name, as the workflow spells it Options: --wait-timer <minutes> delay before the job may start; 0 removes it --reviewer <who...> user:<login>, team:<org/slug>, or a bare login (a user) --branch-pattern <glob...> refs permitted to deploy here (main, releases/*, v?.0) --prevent-self-review refuse an approval from whoever triggered the run --allow-self-review permit it (the default) -h, --help display help for command

apex environment delete

Usage: apex environment delete [options] <repository> <name> Remove an environment protection rule (repository admin) Arguments: repository owner/repo name environment name Options: -h, --help display help for command

apex deployment

Usage: apex deployment [options] [command] Deployments: what is waiting for an approval, and giving one Options: -h, --help display help for command Commands: list [options] Deployments waiting for approval, or every deployment of one run approve [options] <id> Approve one waiting deployment reject [options] <id> Reject one waiting deployment help [command] display help for command

apex deployment list

Usage: apex deployment list [options] Deployments waiting for approval, or every deployment of one run Options: --run <id> one run, in the order it deployed --json machine-readable output -h, --help display help for command

apex deployment approve

Usage: apex deployment approve [options] <id> Approve one waiting deployment Arguments: id deployment id (apex deployment list prints them) Options: --comment <text> recorded with the decision -h, --help display help for command

apex deployment reject

Usage: apex deployment reject [options] <id> Reject one waiting deployment Arguments: id deployment id (apex deployment list prints them) Options: --comment <text> recorded with the decision -h, --help display help for command

apex approval

Usage: apex approval [options] [command] Runs from forks: what is waiting, and deciding it (ADR-0024) Options: -h, --help display help for command Commands: list [options] Runs from a fork waiting for somebody with write access to approve them approve [options] <run-id> Approve one run from a fork — it starts with no secrets and on a runner of its own reject [options] <run-id> Reject one run from a fork — every job fails and the attempt is closed help [command] display help for command

apex approval list

Usage: apex approval list [options] Runs from a fork waiting for somebody with write access to approve them Options: --json machine-readable output -h, --help display help for command

apex approval approve

Usage: apex approval approve [options] <run-id> Approve one run from a fork — it starts with no secrets and on a runner of its own Arguments: run-id run id (apex approval list prints them) Options: --comment <text> recorded with the decision -h, --help display help for command

apex approval reject

Usage: apex approval reject [options] <run-id> Reject one run from a fork — every job fails and the attempt is closed Arguments: run-id run id (apex approval list prints them) Options: --comment <text> recorded with the decision -h, --help display help for command

apex schedule

Usage: apex schedule [options] [command] Schedules: what `on: schedule` will fire, and when Options: -h, --help display help for command Commands: list [options] <repository> What a repository has scheduled, and when each fires next help [command] display help for command

apex schedule list

Usage: apex schedule list [options] <repository> What a repository has scheduled, and when each fires next Arguments: repository owner/repo Options: --json machine-readable output -h, --help display help for command

apex oidc

Usage: apex oidc [options] [command] OIDC: what this issuer publishes, and what a token says it is Options: -h, --help display help for command Commands: discovery [options] The OIDC discovery document, as a cloud provider fetches it subject <repository> A repository's OIDC subject claim (repository admin) help [command] display help for command

apex oidc discovery

Usage: apex oidc discovery [options] The OIDC discovery document, as a cloud provider fetches it Options: --json machine-readable output -h, --help display help for command

apex oidc subject

Usage: apex oidc subject [options] [command] <repository> A repository's OIDC subject claim (repository admin) Arguments: repository owner/repo Options: -h, --help display help for command Commands: set [options] <repository> Fold claims into the subject, or reset to the default with no --claim

apex oidc subject set

Usage: apex oidc subject set [options] <repository> Fold claims into the subject, or reset to the default with no --claim Arguments: repository owner/repo Options: --claim <key...> claim keys, in the order they appear in the subject -h, --help display help for command

apex actions

Usage: apex actions [options] [command] The action supply chain: what a repository pulls in, the policy over it, and pinning Options: -h, --help display help for command Commands: list [options] <repository> Every action a repository pulls in, least fixed first policy [options] <owner> Read or replace an organisation's action policy pin [options] <repository> Propose pinning every action to the commit its version points at help [command] display help for command

apex actions list

Usage: apex actions list [options] <repository> Every action a repository pulls in, least fixed first Arguments: repository owner/repo Options: --json machine-readable output -h, --help display help for command

apex actions policy

Usage: apex actions policy [options] <owner> Read or replace an organisation's action policy Arguments: owner the organisation Options: --mode <mode> off · audit · enforce — omit to read the policy rather than change it --allow <patterns...> patterns that may be used; empty means everything not denied --deny <patterns...> patterns that may not be used; deny wins over allow --require-pinned require a commit SHA (or an image digest); a version tag does not count. Omit to permit tags --json machine-readable output -h, --help display help for command

apex actions pin

Usage: apex actions pin [options] <repository> Propose pinning every action to the commit its version points at Arguments: repository owner/repo Options: --apply open the pull request; without this the change is only printed --json machine-readable output -h, --help display help for command

apex terms

Usage: apex terms [options] [command] The customer agreement: who owes an acceptance of the terms in force, and the escalation path Options: -h, --help display help for command Commands: pending [options] Accounts that owe an acceptance of the customer terms in force accept [options] <installationId> Accept for one account as the machine token — the escalation path, not the normal one help [command] display help for command

apex terms pending

Usage: apex terms pending [options] Accounts that owe an acceptance of the customer terms in force Options: --json machine-readable output -h, --help display help for command

apex terms accept

Usage: apex terms accept [options] <installationId> Accept for one account as the machine token — the escalation path, not the normal one Arguments: installationId the installation the account is on Options: --confirm record the acceptance; without it nothing is written --json machine-readable output -h, --help display help for command

apex notify

Usage: apex notify [options] [command] Notification routing: where a repository’s outcome changes are sent Options: -h, --help display help for command Commands: list [options] <repository> The rules for one repository, and how each one last fared add [options] <repository> <name> Create or replace one rule rm <repository> <name> Remove one rule, and the record of its deliveries test [options] <repository> <name> Send a message to one destination now, and report what it said log [options] <repository> The last attempts to reach this repository’s destinations help [command] display help for command

apex notify list

Usage: apex notify list [options] <repository> The rules for one repository, and how each one last fared Arguments: repository owner/repo Options: --json machine-readable output -h, --help display help for command

apex notify add

Usage: apex notify add [options] <repository> <name> Create or replace one rule Arguments: repository owner/repo name the rule name, e.g. ci-alerts Options: --kind <kind> destination type: slack, teams, webhook (default: "slack") --to <url> the destination URL; omit to be prompted, or to keep the one already stored --on <triggers> comma-separated: broke, recovered, failed, succeeded (default: broke,recovered) (default: []) --workflow <glob> only these workflow paths (repeatable); omit for all (default: []) --branch <glob> only these branches (repeatable); omit for all (default: []) --disable store the rule but send nothing through it --json machine-readable output -h, --help display help for command

apex notify rm

Usage: apex notify rm [options] <repository> <name> Remove one rule, and the record of its deliveries Arguments: repository owner/repo name the rule name Options: -h, --help display help for command

apex notify test

Usage: apex notify test [options] <repository> <name> Send a message to one destination now, and report what it said Arguments: repository owner/repo name the rule name Options: --json machine-readable output -h, --help display help for command

apex notify log

Usage: apex notify log [options] <repository> The last attempts to reach this repository’s destinations Arguments: repository owner/repo Options: --limit <n> how many attempts to show (default 20) (default: "20") --json machine-readable output -h, --help display help for command

apex lsp

Usage: apex lsp [options] Run the workflow language server on stdio, for an editor to start as a child process Options: -h, --help display help for command Configure your editor to run this for YAML files under .github/workflows. It needs no control plane and no network: the engine parses the buffer in front of you. VS Code contributes.languages + a client that spawns `apex lsp` Neovim vim.lsp.start({ cmd = { 'apex', 'lsp' } }) Helix [language-server.apex] command = "apex", args = ["lsp"] Set APEX_ENGINE_BIN if apex-engine is not on your PATH.