Commands reference
CLI usage, examples, and all options.
Heal CLI commands
The Heal CLI is the command-line entry point to run your Playwright tests with Heal’s self-healing layer, and to use the Autopilot agent to generate or fix tests. It works alongside the Heal SDK and your existing Playwright setup.
Overview
heal test: Run your Playwright tests with Heal’s self-healing runner and caching.heal autopilot: Use the Autopilot agent to generate, fix, or refactor tests.heal init: Scaffold a Heal-aware repository structure in your project.heal login: Authenticate your Heal CLI and store your API token.heal view: Open a local test report viewer
Usage
heal <command> [options]
heal test [globs...] # Run tests
heal autopilot [request] # Run the Autopilot agent to create/fix tests
heal init # Initialize a Heal repository
heal login # Authenticate and store your API token
heal view [options] # Open local test report viewerGlobal options
These options are available on all commands:
| Option | Description |
|---|---|
--version | Show version. |
-h, --help | Show this help. |
heal test
heal test [globs...] [options]Description
heal test runs your Playwright tests with Heal’s self-healing layer enabled.
For a deeper walkthrough of running and tuning tests, see Running tests.
Common examples
# Run all tests
heal test
# Run a specific test
heal test "tests/login.spec.ts"
# Run tests matching a glob
heal test "tests/**/*.spec.ts"
# Run 4 tests in parallel
heal test --concurrency 4
# Run in headless mode
heal test --headless true
# Retry failing tests 3 times
heal test --retries 3Options
| Option | Type | Default | Description |
|---|---|---|---|
--concurrency <n> | number | 1 | Parallel test count. |
--timeout <ms> | number | 30000 | Per-test timeout in milliseconds. |
--headless <bool> | boolean | — | Headless browser mode. |
--retries <n> | number | 2 | Retry attempts on failure. |
--wait-before-ai <ms> | number | 0 | Wait before AI calls in milliseconds. |
--wait-before-cache <ms> | number | 300 | Wait before cache lookup in milliseconds. |
--smart-wait-timeout <ms> | number | 7000 | Smart wait before AI in milliseconds. |
--worker-heap <mb> | number | — | Worker max old-gen heap size in megabytes. |
--worker-young <mb> | number | — | Worker max young-gen heap size in megabytes. |
heal autopilot
heal autopilot [request] [options]Description
heal autopilot runs the Autopilot agent.
Optionally pass the first command (for example, heal autopilot "fix login test").
For a full guide to how Autopilot creates tests, see Creating tests.
Examples
# Start autopilot in interactive mode
heal autopilot
# Run autopilot with a request
heal autopilot "fix login test"
# Run autopilot from a test case file in an agentic loop
heal autopilot "implement the test from the instructions at testCase.txt" --headless true --interactive falseOptions
| Option | Type | Default | Description |
|---|---|---|---|
--headless <bool> | boolean | false | Headless browser mode. |
--interactive <bool> | boolean | true | If true, the autopilot asks questions interactively. |
heal init
heal initDescription
heal init initializes a Heal start repo structure for your end-to-end tests.
Example
heal initheal login
heal login [options]Description
heal login authenticates your Heal CLI.
Examples
npx heal login
heal loginheal view
heal view [options]Description
heal view starts a local web server that browses Heal reports. It always uses the current working directory and looks for a heal-report folder there (for example, after heal test).
Examples
# Default viewer on port 3000
heal view
# Custom port
npx heal view --port 4000Options
| Option | Type | Default | Description |
|---|---|---|---|
--port <n> | number | 3000 | Port for the local report viewer. |
See also
To learn how the CLI fits into the rest of the ecosystem (SDK, platform, and more), start from the main CLI reference and the SDK overview.