Skip to main content

Agnox CLI

agnox brings Agnox to your terminal and CI pipelines. Use it to list runs, print the failures of a run, trigger a run and wait for its result, and export manual test cases as Playwright spec skeletons.

It ships in the same npm package as the MCP server, talks only to the Public API v1, and needs Node.js 20 or later.


Installation​

Run it once with npx, without installing:

npx -p @agnox/mcp-server agnox --help

Or install it globally:

npm install -g @agnox/mcp-server
agnox --help

Or add it to a project, so CI uses a pinned version:

npm install -D @agnox/mcp-server
npx agnox --help

The package name is @agnox/mcp-server and the command is agnox. With npx and no install, pass -p @agnox/mcp-server so npx knows which package provides the agnox command.

Configuration​

The CLI uses three settings:

VariableRequiredDefaultPurpose
AGNOX_API_KEYYesAPI key from Settings → My Profile → API keys
AGNOX_API_URLNohttps://api.agnox.devThe Agnox API host, for a self-hosted install (https:// only, except for localhost). Not the dashboard URL. A trailing /api, /api/v1 or /api/executions/ingest is removed.
AGNOX_PROJECT_IDNoDefault project, used when --project is omitted

They are read from these places, in this order:

  1. Environment variables, which always win.
  2. A .env file in the current directory. Only the three names above are read, and nothing in your environment is overridden.
  3. Credentials saved by agnox login.

Log in once​

agnox login --api-key "<your key>"
# Logged in to api.agnox.dev (3 projects). Saved to /home/you/.agnox/config.json

agnox login checks the key against the API first and saves nothing if the key is rejected. For a self-hosted install, add --api-url https://agnox.example.com. The file is created readable by your user only (mode 0600 on macOS and Linux). Delete ~/.agnox/config.json to log out.

Or use a .env file​

# .env in your project (keep it out of git)
AGNOX_API_KEY=<your key>
AGNOX_PROJECT_ID=<project id>

Key and URL stay together. An AGNOX_API_URL from .env is used only together with the AGNOX_API_KEY from the same file. A key from your environment or from agnox login is never sent to a URL that a .env file supplies. This way, a .env in a repository you cloned can't redirect your key to another server. The CLI prints a notice when it ignores such a URL.

Results go to stdout and diagnostics to stderr, so you can pipe --json output into jq safely.


Commands​

CommandDescription
agnox runs listTable of recent runs
agnox runs failures <taskId>Failed tests of one run
agnox triggerStart a hosted run, and optionally wait for it to finish
agnox export-specsWrite Playwright skeletons for manual test cases
agnox loginCheck an API key and save it in ~/.agnox/config.json
agnox mcpRun the MCP server on stdio
agnox --help, agnox --versionUsage and version

agnox runs list​

agnox runs list [--project <id>] [--status <s>] [--limit <n>] [--json]

Prints recent runs, newest first, with task id, status, start time, duration and passed/failed counts.

OptionDescription
--project <id>Project to list (default AGNOX_PROJECT_ID, else every project)
--status <s>Comma-separated filter: PENDING, RUNNING, PASSED, FAILED, ERROR, UNSTABLE
--limit <n>How many runs to show (the API caps this at 100)
--jsonPrint the API data as JSON
agnox runs list --status FAILED --limit 5

agnox runs failures​

agnox runs failures <taskId> [--json]

Prints one block per failed test: name, spec file, failure signature and the first lines of the error. With --json, it prints the full failure data, including the page context captured at the moment of failure.

agnox runs failures run-k3j2

agnox trigger​

agnox trigger --image <img> --command <cmd> --env <development|staging|production>
[--project <id>] [--base-url <url>] [--folder <path>]
[--wait] [--timeout <sec>] [--json]

Starts a run on Agnox's hosted runners.

OptionDescription
--image <img>Required. Docker image that contains your tests
--command <cmd>Required. Command that runs them, for example npx playwright test
--env <env>Required. development, staging or production
--project <id>Project to run in (default AGNOX_PROJECT_ID)
--base-url <url>Base URL of the application under test
--folder <path>Test folder to run (default: all tests)
--waitPoll every 5 seconds until the run finishes, then exit with its result
--timeout <sec>Give up waiting after this many seconds (default 1800)
--jsonPrint the started run, or with --wait the finished run, as JSON
agnox trigger --image ghcr.io/acme/e2e:latest \
--command "npx playwright test" --env staging --wait
# Started run run-k3j2; waiting for it to finish…
# Run run-k3j2 PASSED — 120 passed, 0 failed in 4m 10s

agnox export-specs​

agnox export-specs --out <dir> [--project <id>] [--folder <path>] [--force]

Exports the project's manual test cases as Playwright spec skeletons, one file per top-level folder (for example, a Checkout folder becomes checkout.spec.ts). Cases outside any folder go to root.spec.ts. Automated test cases are skipped, because they already have a spec.

OptionDescription
--out <dir>Required. Directory to write into. It is created if missing.
--project <id>Project to export (default AGNOX_PROJECT_ID)
--folder <path>Export only this folder, for example /Checkout
--forceOverwrite existing files. Without it, nothing is written if any target file exists.

Safety rules: only flat, lower-case *.spec.ts names are written (at most 500 files, 5 MB each), nothing is written outside --out, and symbolic links are never written through.

See Migrate & export test cases for what a generated file looks like.

agnox mcp​

Runs the MCP server on stdio. It takes no arguments and is configured through the same environment variables.


Exit codes​

CodeMeaning
0Success. With trigger --wait, the run finished as PASSED.
1API error, usage error, missing configuration, or a trigger --wait timeout
2trigger --wait only: the run finished but didn't pass (FAILED, ERROR or UNSTABLE)

Code 2 lets a pipeline tell "the tests failed" apart from "the pipeline couldn't reach Agnox".

Use in CI​

GitHub Actions​

- name: Run E2E suite on Agnox
run: npx -p @agnox/mcp-server agnox trigger --image ghcr.io/acme/e2e:latest --command "npx playwright test" --env staging --wait
env:
AGNOX_API_KEY: ${{ secrets.AGNOX_API_KEY }}
AGNOX_PROJECT_ID: ${{ vars.AGNOX_PROJECT_ID }}

The job fails when the run fails, because agnox exits with code 2.

GitLab CI​

e2e:
image: node:22
script:
- npx -p @agnox/mcp-server agnox trigger --image $E2E_IMAGE --command "npx playwright test" --env staging --wait --timeout 3600
variables:
AGNOX_PROJECT_ID: "665f…"
# AGNOX_API_KEY comes from a masked CI/CD variable

Treat a failed run differently from an outage​

set +e
agnox trigger --image "$IMAGE" --command "npx playwright test" --env staging --wait
code=$?
set -e
if [ "$code" -eq 2 ]; then echo "Tests failed"; exit 1; fi
if [ "$code" -ne 0 ]; then echo "Could not reach Agnox, skipping the gate"; exit 0; fi