CLI reference

For prose walkthroughs see Guides → Using the CLI. This page is the flat reference.

Synopsis

blop [command] [patterns] [options]

If command is omitted, test is used. If patterns are omitted, defaults to **/*.blop.ts and **/*.blop.tsx. Files matching node_modules/, dist/, .blop/, and .git/ are always skipped.

Commands

Command	Behavior
blop / blop test	Discover specs, run them, write reports, exit non-zero on any failure.
blop run [patterns]	Same as test.
blop watch [patterns]	Run, then re-run on file change. Polls every 1 s.
blop list [patterns]	Load specs and print discovered test names. No browser launched.
blop init [path]	Scaffold a starter spec at tests/homepage.blop.ts (or the given path).
blop skills <subcommand>	Manage bundled SKILL.md files — see Skills.

blop skills subcommands

Subcommand	Behavior
blop skills list	Print each bundled skill as name@version — description.
blop skills view <name>	Print the full content of a named skill.
blop skills check	Validate all bundled skills. Exits non-zero on hard errors.
blop skills improve <name> [--write]	Distill learnings from .blop/skills journal entries into an improved skill version. Dry-run unless --write.

Options

Discovery & paths

Flag	Short	Type	Default	Notes
--config <file>	-c	string	(auto-discover)	Custom path to blop.config.ts
--report-dir <dir>		string	.blop	Output directory for artifacts

App under test

Flag	Short	Type	Default	Notes
--base-url <url>	-u	string	(none)	Resolved against relative agent.goto("/path")

Browser

Flag	Type	Default	Notes
--browser <name>	enum	chromium	chromium, camoufox, firefox, or webkit; Camoufox is experimental and supports local or containerized runs
--headed	boolean	false	Show the browser window
--viewport <WxH>	string	(Playwright default)	Example: --viewport 390x844
--containerized	boolean	false	Run the selected browser in a separate warm Docker container; Chromium uses blop-playwright, Camoufox uses blop-camoufox

Agent

Flag	Type	Default	Notes
--provider <name>	string	env	Khadim provider name
--model <name>	string	env	Model name
--api-key <key>	string	env	API key — prefer env vars for secrets
--max-steps <n>	int	(unlimited)	Hard cap on agent tool steps. Runs stop on finish, timeout, or the no-progress stall guard.
--workers <n>	int	1	Run up to N agent tests concurrently

Reporting & output

Flag	Short	Type	Default	Notes
--reporter <name>	-r	enum	all	basic, json, junit, or all
--verbose	-v	boolean	false	Stream agent events to stderr in real time
--progress-file <file>		string	(none)	Append live NDJSON progress: test_start, action, frame, test_finish
--capture-screenshots		boolean	false	Save a screenshot after each browser action (and stream live frames)
--no-stream		boolean	(stream on)	Disable the live CDP screencast; use per-action screenshots
--frame-interval <ms>	int	200	Min ms between streamed frame progress lines

Help

Flag	Short	Type	Notes
--help	-h	boolean	Print help and exit

Spec file detection

A file is treated as a Blop spec if its filename matches either:

\.blop\.[cm]?[tj]sx?$
\.agent\.[cm]?[tj]sx?$

So homepage.blop.ts, auth.blop.tsx, and smoke.agent.ts all qualify.

Pattern resolution

Patterns are evaluated in this order:

1. If a pattern resolves to an existing file, that file is included.
2. If it resolves to an existing directory, all spec files under it are included recursively.
3. Otherwise the pattern is treated as a glob.

Exit codes

Code	Meaning
0	Aggregate run status was passed
1	Any test was failed or error, or a CLI error occurred

Environment variables

See Environment variables for the full reference.