Documentation
CLI Reference
Every command, flag, environment variable, and exit code.
The blop binary ships with @blopai/cli. Once the package is installed you
can call blop directly; without installing, use npx @blopai/cli <command>.
Synopsis
blop [command] [patterns] [options]If command is omitted, test is used. If patterns are omitted, Blop
defaults to **/*.blop.ts and **/*.blop.tsx. Files under 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). |
Options
| Flag | Short | Default | Notes |
|---|---|---|---|
--base-url <url> |
-u |
(none) | Resolved against relative agent.goto("/path") |
--report-dir <dir> |
.blop |
Output directory for artifacts | |
--headed |
false |
Show the browser window | |
--browser <name> |
chromium |
chromium, firefox, or webkit |
|
--viewport <WxH> |
(Playwright default) | Example: --viewport 390x844 |
|
--config <file> |
-c |
(auto-discover) | Custom path to blop.config.ts |
--provider <name> |
env | Agent provider name | |
--model <name> |
env | Model name | |
--api-key <key> |
env | API key (prefer environment variables) | |
--max-steps <n> |
100 |
Per-test agent step budget | |
--reporter <name> |
-r |
all |
basic, json, junit, or all |
--verbose |
-v |
false |
Stream agent events to stderr |
--help |
-h |
Print help and exit |
Spec file detection
A file is treated as a Blop spec if its name matches either pattern:
\.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:
- A pattern that resolves to an existing file includes that file.
- A pattern that resolves to an existing directory includes every spec under it, recursively.
- Otherwise the pattern is treated as a glob.
Environment variables
| Variable | Used for |
|---|---|
BLOP_AGENT_PROVIDER |
Default agent provider |
BLOP_AGENT_MODEL |
Default model |
BLOP_AGENT_API_KEY |
Default API key |
BLOP_AGENT_BASE_URL |
Override the provider base URL (self-hosted gateways) |
BLOP_PLATFORM_URL |
Blop Platform ingest URL |
BLOP_API_KEY |
Blop Platform API key |
OPENAI_API_KEY |
Native fallback when provider is openai |
OPENROUTER_API_KEY |
Native fallback when provider is openrouter |
GROQ_API_KEY |
Native fallback when provider is groq |
XAI_API_KEY |
Native fallback when provider is xai |
MISTRAL_API_KEY |
Native fallback when provider is mistral |
CEREBRAS_API_KEY |
Native fallback when provider is cerebras |
NVIDIA_API_KEY |
Native fallback when provider is nvidia |
BLOP_DEBUG |
When set, prints stack traces on CLI errors |
Exit codes
| Code | Meaning |
|---|---|
0 |
Aggregate run status was passed |
1 |
A test failed or errored, or a CLI error occurred |