Run browser checks with the CLI

Note

Local OpenTelemetry is Blop’s primary entry point. Use this supported runner when a specific browser flow needs active evidence. For passive monitoring commands, see the CLI reference and first steps.

The blop browser-check commands discover and run authored .blop.ts specs. The bounded agent loop operates the browser through Browser Harness’s explicit tools and records flow evidence. For the exhaustive flag table see Reference → Commands.

Invocation shape

blop [command] [patterns] [options]

Use an explicit browser command. Bare blop starts the local monitoring collector. If no patterns follow blop test, Blop falls back to **/*.blop.ts and **/*.blop.tsx.

$ blop test                         # discover and run every browser check
$ blop test tests/homepage.blop.ts  # run a single file
$ blop test "tests/**/*.blop.ts"    # explicit glob

Commands

blop test

Runs every discovered spec, writes reports, exits non-zero on any failure.

$ blop test --base-url http://localhost:3000 --reporter all

blop run

Same as test. Exists for readability when you want to highlight that you’re targeting a specific file:

$ blop run tests/critical-flow.blop.ts

blop watch

Reruns affected tests on file change. Polls every second.

$ blop watch tests/

Press Ctrl+C to stop.

blop list

Loads spec files and prints discovered test names without launching a browser. Useful for CI sanity checks and IDE integrations.

$ blop list
tests/homepage.blop.ts
  homepage > loads
tests/auth.blop.ts
  auth > sign-in works

blop init [path]

Scaffolds a starter spec at tests/homepage.blop.ts (or the path you provide).

$ blop init                       # creates tests/homepage.blop.ts
$ blop init tests/login.blop.ts   # custom path

blop skills

Manage bundled SKILL.md files. See Skills for the full guide.

$ blop skills list                # list bundled skills
$ blop skills view <name>         # view a skill's full content
$ blop skills check               # validate all skills
$ blop skills improve <name>      # distill learnings into a skill (--write to save)

Options

Browser

Flag	Short	Default	Notes
--base-url <url>	-u	(none)	Resolved against relative agent.goto("/path")
--headed		false	Show the browser window
--browser <name>		chromium	chromium, camoufox, firefox, or webkit
--viewport <WxH>		(Playwright default)	Example: --viewport 390x844
--containerized		false	Run the selected browser in a separate warm Docker container

Agent

Flag	Default	Notes
--provider <name>	env	Supported native-loop provider
--model <name>	env	Model name
--api-key <key>	env	API key (prefer env vars for secrets)
--max-steps <n>	(unlimited)	Hard cap on agent tool steps
--workers <n>	1	Run up to N agent tests concurrently

Reporting

Flag	Short	Default	Notes
--reporter <name>	-r	all	basic, json, junit, or all
--verbose	-v	false	Stream agent events to stderr
--report-dir <dir>		.blop	Output directory for artifacts
--progress-file <file>		(none)	Append live NDJSON progress
--capture-screenshots		false	Save a screenshot after each browser action

Other

Flag	Short	Notes
--config <file>	-c	Custom path to blop.config.ts
--help	-h	Print help and exit

For the exhaustive flag table, see Reference → Commands.

Environment variables

Variable	Used for
BLOP_AGENT_PROVIDER	Default agent provider
BLOP_AGENT_MODEL	Default model
BLOP_AGENT_API_KEY	Default API key
BLOP_INGEST_URL	Blop Platform ingest URL
BLOP_INGEST_SECRET	Per-project ingest secret
BLOP_PROJECT_ID	Project that owns the run
Provider-native	OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY, MISTRAL_API_KEY, CEREBRAS_API_KEY, NVIDIA_API_KEY
BLOP_DEBUG	When set, prints stack traces on CLI errors

See Reference → Environment variables for the full list.

Exit codes

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

Common invocations

# Local dev — fast feedback, headed browser
blop watch tests/ --headed --base-url http://localhost:3000

# CI — full reporting, deterministic budget
blop test --base-url $APP_URL --reporter all --max-steps 75

# Mobile viewport smoke
blop test tests/mobile.blop.ts --viewport 390x844

# Run tests in parallel (up to 3 concurrent)
blop test --workers 3

# Containerized browser (no local Playwright install needed)
blop test --containerized

# Inspect what would run
blop list "tests/**/*.blop.ts"

# Stream live progress to a file
blop test --progress-file .blop/live.ndjson

Next steps

• Reference → Commands — exhaustive flag table
• Configuration — blop.config.ts end to end
• CI integration — GitHub Actions and JUnit ingest
• Production-target browser checks — safeguards before selecting production