Skip to content
Blopblop docs

Using the CLI

The blop command is the primary way to discover, run, and inspect tests. This guide is the readable walk-through; for the exhaustive flag table see Reference → Commands.

Invocation shape

Section titled “Invocation shape”
Terminal window
blop [command] [patterns] [options]

If no command is given, test is implied. If no patterns are given, Blop falls back to **/*.blop.ts and **/*.blop.tsx.

Terminal window
$ blop                              # discover and run everything
$ blop test                         # same
$ blop test tests/homepage.blop.ts  # run a single file
$ blop test "tests/**/*.blop.ts"    # explicit glob

Commands

Section titled “Commands”

blop test (default)

Section titled “blop test (default)”

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

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

blop run

Section titled “blop run”

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

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

blop watch

Section titled “blop watch”

Reruns affected tests on file change. Polls every second.

Terminal window
$ blop watch tests/

Press Ctrl+C to stop.

blop list

Section titled “blop list”

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

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

blop init [path]

Section titled “blop init [path]”

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

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

blop skills

Section titled “blop skills”

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

Terminal window
$ 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

Section titled “Options”

Browser

Section titled “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

Section titled “Agent”
Flag Default Notes
--provider <name> env Khadim 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

Section titled “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

Section titled “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

Section titled “Environment variables”
Variable Used for
BLOP_AGENT_PROVIDER Default agent provider
BLOP_AGENT_MODEL Default model
BLOP_AGENT_API_KEY Default API key
BLOP_PLATFORM_URL Blop Platform ingest URL
BLOP_API_KEY Blop Platform API key
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

Section titled “Exit codes”
Code Meaning
0 Aggregate run status was passed
1 Any test was failed or error, or a CLI error occurred

Common invocations

Section titled “Common invocations”
Terminal window
# 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

Section titled “Next steps”