CLI

The Upliftr CLI runs E2E suites from a terminal or CI. It's the gate a CI job runs: it drives the cross-platform Playwright runner, writes reports, prints a concise summary, and exits with a code CI can act on.

upliftr <command> [args]

The upliftr command ships in the container image (used by the GitHub Action and GitLab template) and installs locally with uv pip install -e backend (or pip install -e backend) — so the same command runs identically on your machine and in CI.

It needs ANTHROPIC_API_KEY in the environment — or a key saved in the dashboard (Settings → AI) — to drive the LLM. The engine and runtime deps (Playwright, the Anthropic SDK, PyYAML) are imported lazily, so --help works without them.

run, run suites (the CI gate)

upliftr run <suite_path_or_glob> [--file-issues PROVIDER] [--out DIR] [--headed]

Argument	Description
suite	A suite file, or a glob like suites/*.upliftr.yaml (recursive ** works). A bare existing path is used as-is.
--file-issues PROVIDER	File failures via this provider, e.g. github (comma-separate for several). Needs the matching env (GITHUB_TOKEN, GITHUB_REPO, …).
--out DIR	Directory for report.json / junit.xml / report.html (default artifacts). Multiple suites land in per-suite subdirs.
--headed	Run with a visible browser (default: headless, required for CI).

ANTHROPIC_API_KEY=sk-ant-... upliftr run "../examples/suites/*.upliftr.yaml" \
  --file-issues github --out artifacts

It prints a per-suite summary, a line per non-passing case, a TOTAL line, where reports were written, and a machine-readable line the GitHub Action scrapes:

::upliftr-output:: passed=3 failed=1 broken=0 skipped=0

test-url, ad-hoc, no suite file

Open a URL and drive it through plain-English steps, the quick-test flow from the terminal.

upliftr test-url <url> "<instructions>" [--headed]

Steps are split on newlines, ;, or the word then:

ANTHROPIC_API_KEY=sk-ant-... upliftr test-url \
  https://app.example.com/login \
  "Type your email and password; then click Sign in; then confirm the dashboard loads"

It prints the agent's progress per step, the final URL, and the first 800 characters of the final page text. A step that can't be carried out exits 2 (broken).

Exit codes

The exit code is the gate, the same everywhere (CLI, GitHub Action, GitLab CI):

Code	Meaning
0	All cases passed.
1	At least one case failed (an assertion didn't hold).
2	At least one case is broken (the run couldn't be carried out).
3	Spec / config error (bad path, no suites matched, missing ANTHROPIC_API_KEY).

Broken (2) outranks failed (1) outranks ok (0).

Issue-filing env

When --file-issues is set, the CLI reads tracker credentials from the environment (the same names as Settings). The CI integrations also inject GIT_SHA and CI_RUN_URL so filed issues carry the commit and the run link.

Related: CI · Filing issues · Settings & env