Quickstart

Install Blop, record a sample failure, and query it, all on your machine.

Quickstart prerequisites

• Node.js 22.18 or newer.
• @blopai/cli 1.8.0 or newer for blop demo. npm may still serve 1.7.0: check with blop --version, and if it is older, replace blop demo (step 2 of the next section) with your own telemetry.

You need no account, API key or model. The demo needs no OpenTelemetry SDK; the own-telemetry path uses the exporter your app already has.

Install the Blop CLI

npm

npm install --global @blopai/cli

pnpm

pnpm add --global @blopai/cli

bun

bun add --global @blopai/cli

A global install lets Blop observe coding agents in every repository. To pin the version in one project, add it as a dev dependency instead, for example pnpm add -D @blopai/cli.

Record and query sample telemetry

1. Start the collector in the background:

   blop up --detach

   It prints the collector URL, http://127.0.0.1:27811 by default, and the Inspector URL. A collector that is already running is reused.

2. Record a sample failure:

   blop demo

   This records two runs of npm test: one that passed, and one that failed after a coding agent’s tool call made an app’s POST /api/pay return 500. Everything it writes is tagged blop.demo=true.

3. List the traces:

   blop traces --json

4. Audit the last 15 minutes:

   blop audit --json

5. Open the Inspector:

   blop open

   When a coding agent runs it, or there is no display, it prints the URL instead of opening a browser.

Check the Blop install worked

blop traces --json prints one JSON document on stdout and exits 0. Trimmed, it looks like this:

{
  "schema_version": "blop.cli/v1",
  "command": "traces",
  "ok": true,
  "data": [
    {
      "trace_id": "303f22e6782d57be82e8a86ac685ab58",
      "service_name": "blop-demo-agent",
      "root_operation_name": "invoke_agent checkout-agent",
      "duration_ms": 1700,
      "span_count": 4,
      "error_count": 2
    }
  ],
  "page": { "limit": 20, "lookback": "15m", "returned": 2, "truncated": false },
  "warnings": [],
  "next": []
}

Expect two traces from blop-demo-agent, one with an error_count above 0. blop audit --json also exits 0 and lists an error_trace finding whose evidence.trace_id is that trace, with a follow_up command to inspect it. blop why --last explains the failure: the issue, the agent step and the app span it made fail.

Remove the sample data with blop demo --clean --yes. Stop the collector with blop stop; stored telemetry stays on disk.

Send your own telemetry

Point any OTLP/HTTP exporter at the collector:

OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:27811 pnpm test

Or let Blop set the OpenTelemetry variables for the command it starts. blop run also records the command as a run, which blop runs lists:

blop run -- pnpm test

Blop command cheat sheet

Command	What it does
blop up --detach	Start the collector and Inspector in the background, or reuse a running one
blop status --json	Show whether the collector runs, where, and what it stores
blop stop	Stop the background collector
blop demo	Record a sample agent failure
blop run -- <cmd>	Run a command with the OpenTelemetry variables set and record it as a run
blop services --json	List services seen in the lookback window
blop traces --json	Search traces by service, status or duration
blop trace <id> --include logs	Print one trace as a span tree with its logs
blop logs --json	Search logs by service, severity or text
blop audit --json	Produce deterministic findings, compared with a baseline
blop issues --json	List issues, current branch first
blop why --last	Explain the latest failure
blop open	Open the Inspector
blop doctor	Check the setup end to end and print a fix for each failure
blop test	Run browser checks

Next steps after the quickstart

• How it works: the observe, investigate and verify loop.
• Connect a coding agent: capture your agent’s prompts and tool calls.
• Investigate: drill from a failing trace to its spans, logs and findings.