CLI reference

There are two CLIs:

• marriska-runner — fire off a test or test set from your terminal or a CI job. Runs Playwright locally on the machine that invokes it, streams results back to Marriska, and writes an HTML report.
• marriska-agent — a long-running daemon that connects over WebSocket and waits for tests dispatched from the cloud. Use this when you want to run from your laptop or a self-hosted runner without baking test execution into a CI workflow.

Note

Both require an API key (Starter+). For setup walkthroughs see Running tests in GitHub Actions or Setting up the local agent.

Installation

Each CLI is its own npm package.

npm install -g @marriska/runner    # one-shot CI runner
npm install -g @marriska/agent     # persistent local agent

Or use them without installing via npx:

npx @marriska/runner run --test-set "Smoke" --api-key $MARRISKA_API_KEY
npx @marriska/agent --api-key $MARRISKA_API_KEY

After install, run npx playwright install chromium (or firefox / webkit) so Playwright has the browsers it needs.

marriska-runner

marriska-runner <command> [options]

Commands

Command	Description
run	Execute a test or test set. Default if no command is given.
list	List test sets in your org. With --tests, lists every test grouped by folder.
login	Store an API key in the OS keychain so later commands don’t need --api-key.
logout	Clear the stored API key from the keychain.

marriska-agent exposes the same login and logout commands.

Options

Flag	Type	Description	Default
--api-key <key>	string	API key. Falls back to MARRISKA_API_KEY, then the keychain. Required if none stored.	—
--test-set <name-or-id>	string	Test set to run.	—
--test <name-or-id>	string	Single test to run.	—
--browsers <list>	string	Comma-separated browsers.	chromium
--api-url <url>	string	API base URL. Falls back to MARRISKA_API_URL.	https://api.marriska.com/api/v1
--headed	flag	Show the browser window during execution.	headless
--parallel	flag	Run multiple browsers concurrently instead of sequentially.	sequential
--ci	flag	CI mode — don’t auto-open the report; rely on exit code.	off
--no-report	flag	Skip HTML report generation entirely.	off
--report-dir <dir>	string	Directory for the HTML report.	./marriska-reports
--tests	flag	(With list) show tests instead of test sets.	off
-h, --help	flag	Print usage and exit.	—
-v, --version	flag	Print CLI version and exit.	—

You must pass either --test-set or --test to run. Listing alone is fine without either:

marriska-runner list
marriska-runner list --tests

Examples

# Run a single test set in Chromium, write HTML report to ./marriska-reports
marriska-runner run --test-set "Smoke" --api-key ak_live_...

# Run one test, all three browsers, in parallel, headed
marriska-runner run --test "Login flow" \
  --browsers chromium,firefox,webkit \
  --parallel --headed

# CI mode — don't open the report locally, exit code drives the build
marriska-runner run --test-set "Regression" --ci

# Skip the report entirely (smallest footprint)
marriska-runner run --test-set "Smoke" --no-report

Exit codes

Code	Meaning
0	Run completed; all tests passed.
1	At least one test failed, or Playwright browsers aren’t installed (run npx playwright install).
2	Configuration / startup error — missing --api-key, bad flag, network error fetching the test, etc.

The runner exits as soon as the run finishes — it does not poll for schedule-driven re-runs.

marriska-agent

A persistent agent that holds a WebSocket connection to Marriska and runs tests dispatched from the cloud Runner page. One agent per machine, typically.

marriska-agent [start] [options]

Options

Flag	Type	Description	Default
--api-key <key>	string	API key. Falls back to MARRISKA_API_KEY, then the keychain. Required if none stored.	—
--ws-url <url>	string	WebSocket URL. Falls back to MARRISKA_WS_URL.	wss://api.marriska.com/api/v1/ws/agent
--headed	flag	Show browser windows during execution.	headless
--parallel	flag	Run multiple browsers concurrently per dispatched test.	sequential
-h, --help	flag	Print usage and exit.	—
-v, --version	flag	Print agent version and exit.	—

Behavior

When the agent starts, it:

1. Detects which Playwright browsers are installed on the machine and reports them as capabilities.
2. Connects over WebSocket and waits for dispatches from the cloud.
3. Runs each dispatched test locally; streams step events back as the run progresses.
4. Stays connected until you stop it with Ctrl+C (handles SIGINT and SIGTERM cleanly).

If no browsers are installed, the agent exits immediately with the suggestion npx playwright install chromium.

Examples

# Foreground, env var for the API key
MARRISKA_API_KEY=ak_live_... marriska-agent

# Inline key, headed (great for debugging visual flow)
marriska-agent --api-key ak_live_... --headed

# Custom WebSocket URL (self-hosted / staging)
marriska-agent --api-key ak_live_... --ws-url wss://staging.example.com/ws/agent

Exit codes

Code	Meaning
1	Playwright browsers aren’t installed (or the agent crashed mid-run).
2	Missing --api-key / startup error / unhandled exception.

There’s no 0 exit on a daemon — the agent is meant to run until you stop it.

Environment variables

Variable	Equivalent flag	Used by
MARRISKA_API_KEY	--api-key	Both runner and agent
MARRISKA_API_URL	--api-url	Runner
MARRISKA_WS_URL	--ws-url	Agent

--token and MARRISKA_TOKEN are still accepted as deprecated aliases of --api-key / MARRISKA_API_KEY, but they print a deprecation warning — use the --api-key forms.

The API key is resolved in this order: the --api-key flag, then the MARRISKA_API_KEY env var, then the OS keychain (via keytar), then ~/.config/marriska/credentials (mode 0600). In CI, set MARRISKA_API_KEY as a secret.

See also

• Running tests in GitHub Actions — practical CI walkthrough using marriska-runner
• Setting up the local agent — installing and connecting marriska-agent
• API keys — creating and rotating the token both CLIs need
• Cloud vs local execution — when to use which