# Quickstart

> Install the Blop CLI, record sample telemetry with blop demo, and read it back as JSON the way a coding agent does.

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](#send-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**

```bash
npm install --global @blopai/cli
```

**pnpm**

```bash
pnpm add --global @blopai/cli
```

**bun**

```bash
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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   blop traces --json
   ```

4. Audit the last 15 minutes:

   ```bash
   blop audit --json
   ```

5. Open the Inspector:

   ```bash
   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:

```json
{
  "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:

```bash
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:

```bash
blop run -- pnpm test
```

## Blop command cheat sheet

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

## Next steps after the quickstart

- [How it works](/how-it-works/): the observe, investigate and verify loop.
- [Connect a coding agent](/guides/connect-agent/): capture your agent's prompts and tool calls.
- [Investigate](/guides/investigate/): drill from a failing trace to its spans, logs and findings.