# Commands > Every blop command with usage, flags and JSON fields, plus exit codes, environment variables and the JSON output contract. Local observability for coding agents: sessions, traces and issues. ```bash blop [flags] ``` Running `blop` with no command runs `blop home`. ### Global flags | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `-o, --output ` | text (default), json, ndjson or env, per command Values: text, json, ndjson, env. | text | | | `--json` | Same as -o json: one blop.cli/v1 document on stdout | | | | `-p, --port ` | Collector port (default 27811, env BLOP_MONITOR_PORT) | 27811 | `BLOP_MONITOR_PORT` | | `--url ` | Collector URL (env BLOP_MONITOR_URL) | | `BLOP_MONITOR_URL` | | `--no-color` | Disable colour (also NO_COLOR=1) | | `NO_COLOR` | | `--no-input` | Never prompt; a question exits 2 (also BLOP_NO_INPUT=1) | | `BLOP_NO_INPUT` | | `-q, --quiet` | Print only results and errors | | | | `--debug` | Print stack traces (also BLOP_DEBUG=1) | | `BLOP_DEBUG` | | `-h, --help` | Show help for blop or a command | | | | `-V, --version` | Print the version | | | ## Start commands ### blop up Start the collector and inspector, or reuse a running one In a terminal Blop stays in the foreground, with a banner and single keys: o opens the inspector, i the issues, m copies the MCP command, h lists the keys, q quits. It starts in the background instead, and returns once the collector answers, when a coding agent runs it, when stdout is not a terminal, or with --json. Windows always stays in the foreground unless you pass --detach. A collector already running is reused; a background one from an older Blop is restarted. ```bash blop up [--detach | --foreground] [--port ] [--host ] [--project ] [--no-open] [--recover] [--compact] [--json] ``` Aliases: `blop start`. | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--project ` | Default authored-memory project (otherwise BLOP_PROJECT_ID, then all local projects) | | | | `--detach` | Start in the background and return once it answers | | | | `--foreground` | Stay in this terminal, even for an agent or a pipe | | | | `--no-open` | Do not open the inspector (also BROWSER=none) | | | | `--recover` | If the store is corrupt or from a newer Blop, move it aside (renamed, never deleted; the check may already have merged a pending WAL into it) and start an empty one | | | | `--compact` | Before starting, evict to the size cap and VACUUM the store so deleted space returns to the disk (needs twice the store size free; refused while a collector serves it) | | | JSON fields in `data`: `url`, `inspector_url`, `otlp_endpoint`, `port`, `pid`, `instance_id`, `version`, `cli_version`, `store`, `started`, `managed`, `mode`, `log_path`. ```bash blop up # Start the collector and inspector, or reuse a running one blop up --recover # Move a store Blop cannot open aside and start an empty one blop up --detach # Start in the background and print where it runs ``` See also: `blop status`, `blop stop`, `blop help environment`. ### blop run Run a command with telemetry: blop run -- npm run dev With no command it runs the package.json dev script through the package manager the lockfile names (pnpm, yarn, bun, else npm; the lockfile may be in a parent workspace folder) and says so on stderr; a dev script that runs blop itself is refused. Before the command starts, one stderr line names the collector, the service name, whether content capture is on, and the agent SDKs found here (--no-summary drops it and the end summary). Inside another blop run that is still running (BLOP_LOCAL_RUN_ID) the command joins that run instead of starting its own, and its own --capture-content, --url and --port do not apply (it says so); a marker left by an ended run is ignored. --no-summary also drops the coding-agent block. The command keeps this terminal: its stdin, stdout and stderr are its own. With --json, Blop writes one blop.cli/v1 document to stderr after the command exits, and nothing else of its own: the last line Blop writes, on a line of its own, starting with {"schema_version". A background process the command started can still write after it, so --report is the robust path: the document goes to that file (written atomically; if it cannot be written, to stderr with a report_not_written warning). ok is true when the command started, whatever its exit code; data.exit_code is the command's code. Signals: Ctrl-C or SIGTERM while the collector starts exits 130 or 143 and the command never runs (ok false, interrupted). While the command runs, SIGTERM and SIGHUP are forwarded to it (and Ctrl-C when no terminal already sent it); a command still running BLOP_RUN_KILL_GRACE_MS (10000) ms after SIGTERM or SIGHUP is killed, and Ctrl-C twice within 2 seconds kills it at once. After it exits, Ctrl-C skips the wait for late telemetry: the summary still prints (warning settle_interrupted) and the exit code stays the command's. ```bash blop run [--capture-content] [--env ] [--trigger ] [--trigger-id ] [--no-summary] [--json] [--report ] [--] [] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--capture-content` | Ask instrumented GenAI SDKs to record prompt and completion content | | | | `--env ` | deployment.environment.name on the command's telemetry (an OTEL_RESOURCE_ATTRIBUTES value wins) | | | | `--trigger ` | What started the run (blop.trigger.kind): ci, schedule, manual or your own kind; default: detected CI, else manual | | | | `--trigger-id ` | blop.trigger.id: a schedule id or CI run id (CI runs are detected with their run id) | | | | `--report ` | Write the run summary as a blop.cli/v1 document to this file | | | | `--no-summary` | No start line and no end summary on stderr (new issues and warnings still print) | | | JSON fields in `data`: `run_id`, `command`, `command_line`, `cwd`, `git`, `exit_code`, `signal`, `started_at`, `ended_at`, `duration_ms`, `sessions`, `requests`, `failed_requests`, `new_issues`, `regressed_issues`, `collector_url`, `inspector_url`, `recorded`. ```bash blop run -- npm run dev # Run your app with OTel env, git stamp and a run record blop run npm test # The -- is optional: the first non-flag word starts the command blop run --report r.json npm test # Also write the run summary (JSON) to r.json ``` See also: `blop up`, `blop issues`, `blop help environment`. ### blop demo Record a sample agent failure to explore before you instrument anything Through the running collector (started in the background when it is stopped) it records two npm test runs in this repo: one that passed 10 minutes ago and one that failed, where an agent's bash tool call made the app's POST /api/pay answer 500 after the agent read the memory node demo:checkout-policy. Then blop why --last explains it. Everything it records is tagged blop.demo=true; running it again adds an occurrence to the same issue, never a second issue. --clean deletes only data tagged blop.demo=true (its traces with their runs, occurrences and issue, and the demo memory node with its reads): without --yes it only counts them and exits 1. ```bash blop demo [--clean [--yes]] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--clean` | Delete the demo data instead (a preview unless --yes) | | | | `--yes` | With --clean, delete it | | | JSON fields in `data`: `issue_id`, `app_span_id`, `agent_step_span_id`, `runs`, `trace_ids`, `preview`, `traces`, `spans`, `issues`, `memory_nodes`, `memory_reads`. ```bash blop demo # Record the demo failure, then run blop why --last blop demo --clean # Count the demo data that --clean --yes would delete blop demo --clean --yes # Delete the demo data, nothing else ``` See also: `blop why`, `blop delete`. ### blop setup Set up every coding agent on this machine (blop setup agents) blop setup doctor is a read-only whole-loop audit: collector/status, store, browser, runtime, agent recipes, git and binding. Start here when evidence looks empty; failures print exact next commands (exit 1), never auto-repair. blop setup agents detects installed coding agents and installs their supported user-global hooks, starting or reusing a local collector. New capture follows the existing full-content default; --capture metadata-only excludes bodies. Existing capture modes and exclusions are preserved when --capture is omitted. blop setup mcp adds Blop's MCP server (blop mcp) to a coding agent: through the client's own command for Claude Code (claude mcp add), Codex (codex mcp add) and Gemini CLI (gemini mcp add), or by editing one entry in its JSON config for Cursor, VS Code, OpenCode and Pi (comments kept, the previous file copied to Blop's state dir, the file read back). Pi requires pi-mcp-adapter; OMP reads project .mcp.json natively. For Windsurf and Claude Desktop it prints the entry and never writes. First it starts the command and checks that Blop's MCP server answers; a command that would not start is never written (exit 6). A second run changes nothing; a different blop entry is replaced only with --force; --remove undoes it; --print writes nothing. With no client it lists the coding agents it finds and reports stale blop entries (an old pinned version, npx while blop is on PATH, a command that no longer exists) with the command that updates each. ```bash blop setup [flags] ``` | Subcommand | Purpose | Usage | | --- | --- | --- | | `agents` | Detect installed agents and install their supported global hooks | `blop setup agents [--capture full\|conversation-only\|metadata-only] [--url URL\|--port N] [--json]` | | `doctor` | Read-only whole-loop environment audit with exact fix commands | `blop setup doctor [--url URL\|--port N] [--acknowledge-non-loopback] [--json]` | | `plugin` | Prepare Codex or Claude Desktop hosted plugin setup | `blop setup plugin --app-url URL [--print\|--remove] [--force] [--allow-loopback-development] [--json]` | | `mcp` | Add Blop's MCP server to claude, codex, cursor, vscode, opencode, pi, omp, gemini, windsurf, claude-desktop | `blop setup mcp [\|all] [--scope local\|project\|user] [--print] [--force] [--remove] [--json]` | | `opencode` | Configure and start OpenCode monitoring | `blop setup opencode [--port ] [--remove] [--json]` | | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--capture ` | agents: capture mode for detected agents; existing choices are preserved when omitted Values: full, conversation-only, metadata-only. | | | | `--scope ` | mcp: where the entry goes: local, project or user (when omitted, the client decides) Values: local, project, user. | | | | `--print` | Print the setup entry/package instructions, write nothing | | | | `--force` | Replace a different existing Blop entry/package | | | | `--remove` | Remove the selected Blop entry/package instead (opencode: take back its config edits and setup record) | | | | `--app-url ` | plugin: hosted public HTTPS app origin | | | | `--allow-loopback-development` | plugin: explicitly permit Codex loopback development | | | | `--acknowledge-non-loopback` | doctor: acknowledge a non-loopback target (never contacts external hosts) | | | ```bash blop setup agents # Detect installed agents and install global hooks blop setup mcp claude # Let Claude Code read Blop issues over MCP blop setup doctor --json # Audit the whole local loop without changing anything ``` See also: `blop mcp`, `blop doctor`. ### blop init Detect agent frameworks and print or write the OTel setup ```bash blop init [--write] [--mcp ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--write` | Update .gitignore and .env.blop (nothing else is touched) | | | | `--mcp ` | Then add Blop's MCP server to this coding agent: claude, codex, cursor, vscode, opencode, pi, omp, gemini, windsurf or claude-desktop (same as blop setup mcp ) Values: claude, codex, cursor, vscode, opencode, pi, omp, gemini, windsurf, claude-desktop. | | | JSON fields in `data`: `write`, `detections`, `changed`, `mcp`. ```bash blop init # Print the setup lines for the frameworks found here blop init --write # Also update .gitignore and .env.blop blop init --mcp claude # Then let Claude Code read Blop issues over MCP ``` See also: `blop run`, `blop doctor`. ### blop test Authored browser checks: init, add, list, run, watch blop flows is the same group (ls means list). Aliases: test /run -> test run; watch/list -> test watch/list; init --flow -> test init. Evidence is launch provenance, never proof of a fix. Targets still come from the reviewed spec/config or --base-url. Use authorized systems and synthetic data. ```bash blop test init|add|list|run|watch [patterns...] [flags] ``` Aliases: `blop flows`. | Subcommand | Purpose | Usage | | --- | --- | --- | | `init` | Create a starter spec | `blop test init [file] [--force]` | | `add` | Add another starter spec | `blop test add [file] [--force]` | | `list` | List authored checks without a browser | `blop test list [patterns...] [--json]` | | `ls` | Alias for list | `blop flows ls [patterns...] [--json]` | | `run` | Run authored checks, optionally from local evidence | `blop flows run [patterns...] [--from trace \|--from finding ] [flags]` | | `watch` | Re-run checks when specs change | `blop test watch [patterns...] [flags]` | | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `-u, --base-url ` | Base URL for the app under test (local, CI, staging, or HTTPS production) | | | | `--report-dir ` | Report output directory (default .blop) | .blop | | | `--coverage` | Collect executed JavaScript source coverage (Chromium only) | | | | `--coverage-endpoint ` | Send coverage to this local collector base URL (requires --coverage) | | | | `--progress-file ` | Append live NDJSON progress (test_start, action, frame, test_finish) | | | | `--capture-screenshots` | Save a screenshot after each browser action (and stream live frames) | | | | `--no-stream` | Disable the live CDP screencast (use per-action screenshots) | | | | `--frame-interval ` | Min ms between streamed frame progress lines (default 200) | 200 | | | `--force` | init/add: overwrite an existing spec without asking | | | | `--headed` | Run browser headed | | | | `--browser ` | Browser to run: chromium, camoufox, firefox or webkit Values: chromium, camoufox, firefox, webkit. | | | | `--containerized` | Run the browser in a separate warm Docker container | | | | `--viewport ` | Viewport as WIDTHxHEIGHT, for example 390x844 | | | | `-c, --config ` | Config file path | | | | `--provider ` | Agent provider for the native agent loop (env BLOP_AGENT_PROVIDER) | | `BLOP_AGENT_PROVIDER` | | `--model ` | Agent model for the native agent loop (env BLOP_AGENT_MODEL) | | `BLOP_AGENT_MODEL` | | `--api-key ` | Agent API key for the native agent loop (env BLOP_AGENT_API_KEY) | | `BLOP_AGENT_API_KEY` | | `--max-steps ` | Optional hard cap on agent tool steps | | | | `--workers ` | Run up to this many agent tests concurrently (default 1) | 1 | | | `-r, --reporter ` | Report format: basic, json, junit or all Values: basic, json, junit, all. | | | | `--otel-endpoint ` | OTLP/HTTP endpoint for flow telemetry; setting it turns export on (env OTEL_EXPORTER_OTLP_ENDPOINT) | | `OTEL_EXPORTER_OTLP_ENDPOINT` | | `--otel-service-name ` | service.name on exported spans (default blop-runner, env OTEL_SERVICE_NAME) | blop-runner | `OTEL_SERVICE_NAME` | | `--otel-environment ` | deployment.environment.name on exported telemetry | | | | `--otel-propagate` | Send W3C traceparent to the app under test (also BLOP_OTEL_PROPAGATE_TO_APP=1) | | `BLOP_OTEL_PROPAGATE_TO_APP` | | `--otel-propagate-allowlist ` | Comma-separated hosts allowed to receive it (env BLOP_OTEL_PROPAGATE_ALLOWLIST) | | `BLOP_OTEL_PROPAGATE_ALLOWLIST` | | `-v, --verbose` | Print agent stream events in real time | | | | `--from ` | Launch provenance: --from trace or --from finding | | | | `--db ` | Existing local evidence database (env BLOP_MONITOR_DB_PATH) | | `BLOP_MONITOR_DB_PATH` | | `--since ` | Evidence lookback, at most 24h (default 15m) | 15m | | ```bash blop test init # Create a reviewed starter spec blop flows run tests/checkout.blop.ts --from finding app_error --json # Run with bounded local launch provenance blop flows ls # List authored checks ``` ## Investigate commands ### blop issues List issues, current branch first ```bash blop issues [--branch ] [--state open|muted|fixed|all] [--failure-kind ] [--limit ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--branch ` | Only issues seen on this branch | | | | `--failure-kind ` | Only issues whose sessions blop classify most often labeled app_error, tool_error, model_error, guardrail_denied or agent_error Values: app_error, tool_error, model_error, guardrail_denied, agent_error. | | | | `--state ` | open (default), muted, fixed or all Values: open, muted, fixed, all. | open | | | `--limit ` | Maximum issues (default 50) | 50 | | | `--header` | Piped output: print the column names first | | | JSON fields in `data`: `id`, `fingerprint`, `code`, `title`, `agent`, `service`, `severity`, `certainty`, `state`, `status`, `badges`, `occurrences`, `sessions`, `requests`, `on_branch`, `trend_24h`, `trend24h`, `trend7d`, `priority`, `first_seen_ms`, `last_seen_ms`, `first_seen_run_id`, `first_seen_commit`, `first_seen_branch`, `fixed_ms`, `regressed_ms`, `not_seen_in_latest_run`, `failure_kind`, `url`. ```bash blop issues # Open issues, current branch first blop issues --json # Current issues as JSON for a script or agent blop issues --state all --header # Tab-separated with a header row when piped ``` See also: `blop issue`, `blop tail`, `blop help json`. ### blop issue Show one issue: causal chain, evidence and fix context ```bash blop issue [--fix-context | --web] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--fix-context` | Print the issue's fix context (markdown) for a coding agent | | | | `--web` | Open the issue in the inspector (same as blop open ) | | | JSON fields in `data`: `issue`, `status`, `badges`, `chain`, `occurrences`, `selected`, `nav`, `excerpt`, `different`, `activity`, `branches`, `run`, `runs`, `not_seen_in_latest_run`, `cli`, `fix_context_url`, `url`, `id`, `markdown`. ```bash blop issue iss_0123abcd # Causal chain, occurrences and the inspector link blop issue iss_0123abcd --fix-context # Markdown to paste into a coding agent blop issue iss_0123abcd --web # Open it in the inspector ``` See also: `blop issues`, `blop trace`, `blop open`, `blop mcp`. ### blop why Explain a failure: what broke, where, why, and which memory was read Explains one failure with ids: the issue (what broke), the agent step span and the app span it made fail (where), the MAST failure mode or none with a reason, plus the failure kind and where it came from (why), and the memory reads recorded for that session. With no id (or --last) it explains the newest failing run in this repo (real runs before demo runs) through its newest issue, else the newest open issue in this repo or with no project. --all-projects widens that to every project. It ends with the next command and an inspector link. An id this collector does not hold exits 4. ```bash blop why [ | --last] [--all-projects] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--last` | Explain the newest failing run in this repo (the default) | | | | `--all-projects` | With --last, look at runs and issues of every project | | | JSON fields in `data`: `schema`, `target`, `demo`, `issue`, `where`, `why`, `memory`, `next`, `links`, `reason`. ```bash blop why # The newest failure in this repo blop why iss_0123abcd # One issue blop why --last --all-projects --json # The newest failure anywhere, for a coding agent ``` See also: `blop issue`, `blop issues`, `blop open`. ### blop runs List the runs blop run recorded, or inspect one against the previous run Lists the runs `blop run` recorded in this repo, newest first: status, command, branch, when, how long and the issues each run first saw. Runs from other projects, or recorded with no project, are left out and counted on stderr; --all-projects shows them. A run Blop's demo seeded carries (demo). --failed keeps runs that exited non-zero without being stopped by a signal. `blop runs show ` prints one run with the issues it saw and how it differs from the previous run of the same command on the same branch; --timeline adds its spans in time order (at most 200). Each answer ends with the next command and an inspector link. An id this collector does not hold exits 4. ```bash blop runs [--failed] [--since ] [--limit ] [--branch ] [--all-projects] [--json] ``` | Subcommand | Purpose | Usage | | --- | --- | --- | | `show` | One run, compared with the previous run of the same command on the branch | `blop runs show [--timeline] [--json]` | | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--failed` | Only runs that failed (a non-zero exit, not stopped by a signal) | | | | `--since ` | Only runs started within this window, e.g. 15m, 1h, 2d, 7d | | | | `--limit ` | Maximum runs, 1 to 200 (default 20) | 20 | | | `--branch ` | Only runs on this branch | | | | `--all-projects` | Runs of every project, not only this repo | | | | `--header` | Piped output: print the column names first | | | | `--timeline` | show: also list the run's spans in time order | | | JSON fields in `data`: `schema`, `scope`, `filters`, `runs`, `hidden_elsewhere`, `next`, `links`. ```bash blop runs # This repo's recent runs blop runs --failed --since 1h # What failed in the last hour blop runs show run_abcdefghijklmnopqrst --timeline # One run, its comparison and its spans ``` See also: `blop why`, `blop run`, `blop issues`. ### blop tail Stream new issues, runs and sessions as they happen ```bash blop tail [-o text|ndjson] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | JSON fields in `data`: `schema_version`, `type`, `reason`, `id`, `title`, `url`, `state`, `status`, `exit_code`, `signal`, `end_reason`, `kind`, `trace_id`, `service`. ```bash blop tail # Watch new issues, runs and sessions as they happen blop tail -o ndjson # One JSON event per line (--json is the same) ``` See also: `blop issues`. ### blop open Open the inspector at an issue, session, run or trace Opens the inspector page of an issue (iss_...), session (ses_...), run (run_...) or trace (32 hex), or a page: home (the default), sessions, issues, runs, connect or settings, on the collector this folder resolves to. A path starting with / (what the web app's blop open chip copies, e.g. /map?env=production&range=24h) opens that screen of the hosted app the blop auth profile (--profile, default "default") is signed in to. It prints the URL instead of opening a browser with --print or --json, for a coding agent, with --no-input, with BROWSER=none, over SSH and where there is no display. It does not check that the object exists. ```bash blop open [ | | /] [--profile NAME] [--print] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--print` | Print the URL, do not open a browser | | | | `--profile ` | The blop auth profile whose hosted app a /path opens on | | | JSON fields in `data`: `url`, `kind`, `id`, `view`, `opened`. ```bash blop open # The inspector's Home blop open iss_0123abcd # One issue blop open runs --print # Print the Runs page URL (for SSH) ``` See also: `blop issue`, `blop issues`, `blop up`. ### blop evaluation Author source-scoped scores and review annotation queues locally Explicit local authoring, not hosted authority or MCP writes. Grants bind one recorded source, principal and permission set for at most 24 hours. Feedback credentials stay in a trusted backend, never browser code. Every mutation names a stable idempotency key and updates name an expected revision. Corrections never replace recorded output. ```bash blop evaluation [flags] ``` | Subcommand | Purpose | Usage | | --- | --- | --- | | `grant` | Issue a bounded source grant as the local database OS owner | `blop evaluation grant --db PATH --input FILE --token-file NEW_FILE [--json]` | | `revoke` | Revoke one local grant immediately | `blop evaluation revoke --db PATH [--json]` | | `call` | Call the local evaluation HTTP owner with a source-scoped grant | `blop evaluation call --input FILE_OR_DASH --token-file FILE --url URL [--json]` | | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--input ` | Strict JSON input file or - for stdin (maximum 32 KiB) | | | | `--db ` | Explicit local collector database for OS-owner grant administration only | | | | `--token-file ` | Private local evaluation credential file; grant creates it exclusively with mode 0600 | | | ```bash blop evaluation grant --db /tmp/review/telemetry.sqlite --input grant.json --token-file /tmp/review/reviewer.key --json # Create exact-source local human/producer authority without printing the credential blop evaluation call subject --input subject.json --token-file /tmp/review/reviewer.key --url http://127.0.0.1:27811 --json # Resolve an immutable source reference before annotating blop evaluation call scores.put --input score.json --token-file /tmp/review/reviewer.key --url http://127.0.0.1:27811 --json # Author a typed score through the actual local HTTP surface ``` ### blop report Render a bounded local evidence packet without network access One local read-only snapshot; no collector discovery, startup, HTTP, analysis, or upload. Findings are stored issues, flows are retained SDK scenario spans. Outcomes and verification are separate: unknown is never success. --until pins the window; identical evidence and options render identically. JSON generated_at is the window end, not the rendering clock. Save stdout to share; publication is a separate explicit operation. ```bash blop report [--since 2h] [--scope service|session|finding] [--format markdown|junit|json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--db ` | Local collector database (otherwise project/environment configuration) (env BLOP_MONITOR_DB_PATH) | | `BLOP_MONITOR_DB_PATH` | | `--since ` | Window duration, 1m through 1d (default 2h) | 2h | | | `--until ` | Fixed exclusive window end for reproducible rendering (ISO UTC) | | | | `--scope ` | Scope kind: service, session or finding; requires its matching selector Values: service, session, finding. | | | | `--service ` | Exact service name with --scope service | | | | `--session ` | Exact recorded session ID with --scope session | | | | `--finding ` | Exact stored issue/finding ID with --scope finding | | | | `--format ` | Packet format: markdown (default), junit or json Values: markdown, junit, json. | markdown | | | `--limit ` | Source rows per section, 1–100 (default 20) | 20 | | | `--max-bytes ` | Whole output byte cap, 4096–262144 (default 65536) | 65536 | | JSON fields in `data`: `window`, `collector`, `scope`, `limits`, `coverage`, `unavailable`, `truncated`, `reproduce`, `services`, `errors`, `logs`, `findings`, `flows`. ```bash blop report --since 2h --format markdown # Print local evidence for a PR or agent handoff blop report --scope service --service checkout --format junit # Render service evidence for CI (no upload) blop report --since 2h --until 2026-10-21T12:00:00Z --format json # Pin a window for deterministic rendering ``` ### blop failure-context Read bounded source-scoped failure evidence without diagnosing a cause One read-only local-plane snapshot. Source plus at least one selector is required; selectors intersect. Metadata only, with exact IDs, deterministic ranks/reasons, capture coverage and next queries. No inferred links, hosted runs, model diagnosis or verification. Repeat with both --until and --revision; an invalidated snapshot is an explicit conflict. Empty evidence is not a passing check. JSON generated_at is the pinned window end. ```bash blop failure-context --source KEY [--trace ID|--service NAME|--session ID|--attempt ID] [--since 15m] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--source ` | Exact 64-hex source key from /api/observations/sources | | | | `--trace ` | Exact 32-hex retained trace ID | | | | `--span ` | Exact 16-hex span ID within the selected scope | | | | `--log ` | Exact retained decimal log ID within the selected scope | | | | `--service ` | Exact service name within the source | | | | `--session ` | Exact recorded session, never a timestamp association | | | | `--attempt ` | Exact recorded attempt; absent identity remains unknown | | | | `--since ` | Bounded window duration, 1m through 1d (default 15m) | 15m | | | `--until ` | Pinned exclusive window end (ISO UTC) | | | | `--revision ` | Require this evidence revision; stale snapshots are rejected | | | | `--limit ` | Maximum symptoms, 1–100 (default 20) | 20 | | | `--max-bytes ` | Data byte cap, 4096–262144 (default 65536) | 65536 | | | `--deadline-ms ` | Server read deadline, 1–5000 ms (default 2000) | 2000 | | | `--db ` | Read an existing local database instead of HTTP; no collector startup | | | JSON fields in `data`: `schema_version`, `state`, `source`, `collector`, `window`, `scope`, `limits`, `coverage`, `symptoms`, `associations`, `verification`, `independently_recorded_outcomes`, `unavailable`, `next`, `truncated`. ```bash blop failure-context --source "$SOURCE" --trace "$TRACE" --since 15m --json # Read a standalone application failure blop failure-context --source "$SOURCE" --session "$SESSION" --until "$END" --revision "$REVISION" --json # Require the exact retained snapshot ``` ### blop map Show the agent map: who hands work to whom, which apps they touch Reads the collector's agent map over a window: coding-agent sessions and named agents (OTel invoke_agent spans) with runs per hour, error rate and p95, the apps their requests reached, and handoffs recorded by exact parent ids (a parent span, or the parent session a hook reported). Agents active at the same time are never connected. ```bash blop map [--range 1h|24h|7d|30d] [--env ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--range ` | Window: 1h, 24h (default), 7d or 30d | | | | `--env ` | Only runs that recorded this deployment.environment.name | | | ```bash blop map # The last 24 hours, every environment blop map --range 7d --env production --json # A week of production, machine-readable ``` See also: `blop session`, `blop open`. ### blop events Show product events: what users did in your app, and how the newest version changed it Reads the collector's product events over a window: OTel log records that carry an event name (the OTLP event_name field or an event.name attribute), counted per event, with the apps that sent them. When an app's newest service.version was first seen inside the window, each of that app's events also shows its count before and after, over equal windows; the version names the coding agent whose run carried it in the same trace, else none. Names and counts only, never a record's body. ```bash blop events [--range 1h|24h|7d|30d] [--env ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--range ` | Window: 1h, 24h (default), 7d or 30d | | | | `--env ` | Only events that recorded this deployment.environment.name | | | ```bash blop events # The last 24 hours, every environment blop events --range 7d --env production --json # A week of production, machine-readable ``` See also: `blop map`, `blop init`, `blop open`. ### blop classify Label agent runs with intent, outcome and failure kind (a local batch job) run (the default) labels the window's coding-agent sessions and named agents as blop.class.intent (change, operate, explore, converse, unknown), blop.class.outcome (success, failure, running) and blop.class.failure_kind (app_error, tool_error, model_error, guardrail_denied, agent_error). Labels are structural and deterministic: outcome and failure kind come from recorded status, errors and guardrail stops, intent from the tools a run called. --llm lets the configured chat provider (BLOP_AGENT_PROVIDER, _MODEL, _API_KEY; default a free OpenRouter model, BLOP_CLASSIFY_MODEL to override) refine intent from the first retained prompt, for full-capture sessions only. Labels feed Issues, the Agent Map and alert filters; they are evidence aids, not verdicts. list reads the stored labels. Runs outside the collector, which need not be running. ```bash blop classify [run|list] [--range 1h|24h|7d|30d] [--llm] [--relabel] [--failure-kind ] [--outcome ] [--intent ] [--agent ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--range ` | Window: 1h, 24h (default), 7d or 30d Values: 1h, 24h, 7d, 30d. | | | | `--llm` | run: refine intent with the configured model (full-capture sessions only) | | | | `--relabel` | run: label again runs this version already labeled | | | | `--failure-kind ` | list: only this failure kind: app_error, tool_error, model_error, guardrail_denied or agent_error Values: app_error, tool_error, model_error, guardrail_denied, agent_error. | | | | `--outcome ` | list: only this outcome: success, failure or running Values: success, failure, running. | | | | `--intent ` | list: only this intent: change, operate, explore, converse or unknown Values: change, operate, explore, converse, unknown. | | | | `--agent ` | list: only this map agent, e.g. harness:claude-code | | | | `--limit ` | list: at most this many (1-1000, default 200) | | | ```bash blop classify # Label the last 24 hours of runs blop classify list --failure-kind tool_error --json # Runs that failed on a tool, machine-readable BLOP_AGENT_API_KEY=... blop classify --llm --range 7d # Refine a week of intents with the free default model ``` See also: `blop issues`, `blop map`, `blop alerts`. ### blop alerts Alert rules on agent telemetry: list, add, pause, test and route them Rules watch one Agent Map metric (agent_error_rate, agent_p95_ms, app_outcome, handoff_failure_share, memory_low_trust_reads, agent_guardrail_denials) over 1h or 24h, on one node (--target) or the worst one. The collector evaluates them every minute and records each change into or out of firing. blop alerts connect --profile NAME --project ID sends firings to the hosted app with that blop auth profile, which posts them to the project's Slack route; without it they stay local. The same link sends the commits an agent made in a blop run (ids only) to GitHub & CI's Agent-authored view. Rates take 25% or 0.25; p95 takes milliseconds. ```bash blop alerts [list|add|enable|disable|remove|test|connect] [] [flags] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--name ` | Rule name (add) | | | | `--metric ` | Metric (add): agent_error_rate, agent_p95_ms, app_outcome, handoff_failure_share, memory_low_trust_reads or agent_guardrail_denials Values: agent_error_rate, agent_p95_ms, app_outcome, handoff_failure_share, memory_low_trust_reads, agent_guardrail_denials. | | | | `--above ` | Fire when the value is above this (add) | | | | `--below ` | Fire when the value is below this (add) | | | | `--target ` | One map node or edge id (add), e.g. agent:harness:claude-code; default the worst one | | | | `--range ` | Window (add): 1h (default) or 24h Values: 1h, 24h. | | | | `--severity ` | Severity (add): critical, warning or info Values: critical, warning, info. | | | | `--failure-kind ` | agent_error_rate (add): count only runs blop classify labeled app_error, tool_error, model_error, guardrail_denied or agent_error Values: app_error, tool_error, model_error, guardrail_denied, agent_error. | | | | `--send` | test: also deliver a marked test firing to the connected destination | | | | `--profile ` | connect: the blop auth profile that delivers firings | | | | `--project ` | connect: the hosted project whose Slack route gets them | | | | `--disconnect` | connect: keep firings local again | | | ```bash blop alerts add --name "Agent failing" --metric agent_error_rate --above 25% --severity critical # Fire when any agent's error rate passes 25% over the last hour blop alerts add --name "Checkout outcome" --metric app_outcome --below 85% --target app:checkout-web # Watch one app's outcome blop alerts connect --profile team --project # Send firings to the project's Slack route through the hosted app blop alerts test alr_0123456789abcdef --send # Evaluate now and send a marked test firing ``` See also: `blop map`, `blop auth`. ### blop session Show one coding-agent session as an agent graph ```bash blop session [|] [--steps] [--view tree|dag] [--limit ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--conversation ` | A span-only agent conversation id (with --service) | | | | `--service ` | The agent service that carried --conversation | | | | `--steps` | One node per step instead of grouping repeats | | | | `--view ` | Draw the graph as a box tree or an ASCII flowchart | | | | `--limit ` | Maximum graph nodes | | | ```bash blop session # The newest session as an agent tree blop session ses_8f2 --view dag # As a flowchart blop session 4bf92f3577b34da6a3ce929d0e0e4736 --steps --json # Every step, machine-readable ``` See also: `blop trace`, `blop issue`, `blop open`. ### blop replay Step through one coding-agent session: prompts, model turns, tool calls and edit diffs Reads one session's recorded steps in order from the local collector: each prompt, model turn and tool call with its status and timing, and, where the capture policy recorded content, the prompt text, the tool's input and output, and an edit's diff. Content stays local: the hosted app shows the same replay without it. A session captured metadata-only or conversation-only says so and prints the command that turns full capture on. Without an id it replays the newest session; --conversation takes a Claude Code or Codex session id (the hook service by default). ```bash blop replay [||--conversation [--service ]] [--step ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--conversation ` | A hook-captured session id (the host's session id) | | | | `--service ` | The service that carried --conversation (default blop-agent-hook) | | | | `--step ` | Only this step, with its full captured content | | | ```bash blop replay # The newest session, step by step blop replay --conversation 2f1c9a7e-4b1d-4b7e-9f0e-3c6d1a2b8e90 --step 12 # One step of a Claude Code session, with its diff blop replay ses_8f2 --json # Every step, machine-readable ``` See also: `blop session`, `blop agents`, `blop open`. ### blop trace Print one trace as a span tree ```bash blop trace [--include logs] [--web] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--include ` | Also include, comma separated (logs) | | | | `--web` | Open the trace in the inspector (same as blop open ) | | | ```bash blop trace 4bf92f3577b34da6a3ce929d0e0e4736 --include logs # Spans plus their logs blop trace 4bf92f3577b34da6a3ce929d0e0e4736 --web # Open it in the inspector blop session # The same trace as an agent graph ``` See also: `blop issue`, `blop open`, `blop help query`. ### blop metrics Exact retained OTLP metric points and per-series totals Reads bounded durable metric facts, preserving exact numeric and nanosecond strings. Totals remain per series, with known/unknown provenance; they are never added to span-derived usage. Use --source to isolate an exact recorded source. A missing cost or currency is not inferred. ```bash blop metrics [--session ] [--source ] [--since 1h|all] [--name ] [--worktree ] [--limit ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--session ` | Exact recorded session ID (not inferred from traces) | | | | `--source ` | Exact 64-hex recorded source key | | | | `--since ` | Positive integer duration in s, m, h or d, or all (default 24h) | 24h | | | `--name ` | Exact metric name | | | | `--worktree ` | Exact recorded worktree | | | | `--limit ` | Maximum raw points, 1 to 10000 (default 100) | 100 | | JSON fields in `data`: `filters`, `window`, `points`, `totals`, `truncated`, `limit`, `revision`. ```bash blop metrics --session SESSION --source SOURCE_KEY --since 1h --json # Exact source-scoped metric facts and totals ``` See also: `blop usage`, `blop open`, `blop help json`. ### blop usage Token usage per service, agent or model Sums the token counters already retained on spans (gen_ai.usage.*, codex.turn.token_usage.*). A counter no span reported is unknown, never 0; spans without usage count only in coverage. Input includes cache read/write and output includes reasoning. Cost remains unknown in this span report; blop metrics reads separate recorded metric facts. ```bash blop usage [--since 1h|24h|all] [--service ] [--agent ] [--group-by service|agent|model] [--limit ] [--json] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--host ` | Collector host (default 127.0.0.1, env BLOP_MONITOR_HOST) | 127.0.0.1 | `BLOP_MONITOR_HOST` | | `--since ` | Window: a duration such as 1h or 24h, or all (default 24h) | 24h | | | `--service ` | Only this service | | | | `--agent ` | Only spans with this blop.agent.id | | | | `--group-by ` | Group by service (default), agent or model Values: service, agent, model. | service | | | `--limit ` | Maximum groups, 1 to 100 (default 20) | 20 | | JSON fields in `data`: `window`, `group_by`, `filters`, `coverage`, `totals`, `cost`, `groups`, `truncated`, `limit`. ```bash blop usage # Tokens per service over the last 24 hours blop usage --since all --group-by model # Tokens per model over everything retained blop usage --agent codex --json # One agent's tokens as a blop.cli/v1 document ``` See also: `blop traces`, `blop help json`. ## Agents commands ### blop mcp Serve issues and sessions to a coding agent over MCP (stdio) The default local read-only MCP server preserves list_issues, get_issue, get_fix_context and get_session, and adds bounded authored-memory reads without implicit model downloads. It speaks both MCP eras: initialize (2024-11-05 to 2025-11-25) and the stateless 2026-07-28 revision (server/discover, per-request _meta). Each call reads the collector of the client's project: BLOP_PROJECT_DIR, else CLAUDE_PROJECT_DIR, else the working directory; --url or BLOP_MONITOR_URL pins one. When several collectors run and none matches, a call says which run and how to choose (BLOP_MONITOR_URL); it never guesses. Add it to a coding agent with blop setup mcp (claude, codex, cursor, vscode, opencode, pi, omp, gemini, windsurf, claude-desktop). Use --target web --profile NAME only for the optional official-SDK bridge to hosted management; it preserves actual enabled schemas and browser approvals, never fetches local telemetry through the web, and never automatically retries a write. ```bash blop mcp [--url ] [--target web --profile NAME] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--target ` | MCP authority: local (default) or web; local remains read-only Values: local, web. | local | | | `--profile ` | Hosted origin/workspace-bound OAuth profile (web target only) | | | ```bash blop setup mcp claude # Register Blop with Claude Code (or any other client) claude mcp add blop -- blop mcp # By hand; blop must be on PATH blop setup mcp # List coding agents and whether blop is registered (and up to date) in each ``` See also: `blop setup mcp`, `blop issues`, `blop issue`. ### blop claude Start Claude Code with Blop capture wired Starts Claude Code with its terminal and exit code: ensures the Blop collector runs, wires Claude Code into Blop for this repo when it is not connected yet (its hooks, Blop's MCP server and the capture binding, project scope, never a prompt; the first launch lists on stderr every file it changed), then runs claude. It fails open: if the collector cannot start or the wiring is refused (a symlinked settings file, drift, a conflicting entry), one warning on stderr names the problem and the fix, and claude starts anyway without capture. To wire an agent without launching it, use blop agents setup and blop setup mcp. Arguments after -- go to claude; without --, every argument but --no-connect does. Before --, only --no-connect, -p and --url are accepted. Blop's help is this page: for Claude Code's own, run blop claude -- --help. A missing claude binary exits 127 with an install hint. ```bash blop claude [--no-connect] [-p | --url ] [-- ] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--no-connect` | Do not connect Claude Code to Blop first; just start it (capture runs only if it is already connected) | | | ```bash blop claude # Start Claude Code, connected to Blop blop claude -- --resume abc # Pass arguments to Claude Code blop claude --no-connect -- --help # Claude Code's own help, without connecting anything ``` See also: `blop agents setup`, `blop setup mcp`, `blop run`. ### blop codex Start Codex with Blop capture wired Starts Codex with its terminal and exit code: ensures the Blop collector runs, wires Codex into Blop for this repo when it is not connected yet (its hooks, Blop's MCP server and the capture binding, project scope, never a prompt; the first launch lists on stderr every file it changed), then runs codex. It fails open: if the collector cannot start or the wiring is refused (a symlinked settings file, drift, a conflicting entry), one warning on stderr names the problem and the fix, and codex starts anyway without capture. To wire an agent without launching it, use blop agents setup and blop setup mcp. Arguments after -- go to codex; without --, every argument but --no-connect does. Before --, only --no-connect, -p and --url are accepted. Blop's help is this page: for Codex's own, run blop codex -- --help. A missing codex binary exits 127 with an install hint. ```bash blop codex [--no-connect] [-p | --url ] [-- ] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--no-connect` | Do not connect Codex to Blop first; just start it (capture runs only if it is already connected) | | | ```bash blop codex # Start Codex, connected to Blop blop codex -- resume --last # Pass arguments to Codex blop codex --no-connect -- --help # Codex's own help, without connecting anything ``` See also: `blop agents setup`, `blop setup mcp`, `blop run`. ### blop opencode Start OpenCode with Blop capture wired Starts OpenCode with its terminal and exit code: ensures the Blop collector runs, wires OpenCode into Blop for this repo when it is not connected yet (its hooks, Blop's MCP server and the capture binding, project scope, never a prompt; the first launch lists on stderr every file it changed), then runs opencode. It fails open: if the collector cannot start or the wiring is refused (a symlinked settings file, drift, a conflicting entry), one warning on stderr names the problem and the fix, and opencode starts anyway without capture. To wire an agent without launching it, use blop agents setup and blop setup mcp. Arguments after -- go to opencode; without --, every argument but --no-connect does. Before --, only --no-connect, -p and --url are accepted. Blop's help is this page: for OpenCode's own, run blop opencode -- --help. A missing opencode binary exits 127 with an install hint. ```bash blop opencode [--no-connect] [-p | --url ] [-- ] ``` | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--no-connect` | Do not connect OpenCode to Blop first; just start it (capture runs only if it is already connected) | | | ```bash blop opencode # Start OpenCode, connected to Blop blop opencode -- --model anthropic/claude-sonnet-4 # Pass arguments to OpenCode blop opencode --no-connect -- --help # OpenCode's own help, without connecting anything ``` See also: `blop agents setup`, `blop setup mcp`, `blop run`. ### blop memory Recall authored memory and read-only Markdown knowledge Unbound reads use the accountless local graph. An explicit repository binding selects hosted reads across subdirectories/worktrees; --scope local stays offline. Bindings contain no credentials and never upload local files. Writes retain explicit scope/profile requirements and expected revisions; organization policy changes require browser approval. ```bash blop memory [flags] ``` | Subcommand | Purpose | Usage | | --- | --- | --- | | `bind` | Bind this Git repository/worktrees to a verified hosted memory project | `blop memory bind --profile NAME --project ID [--json]` | | `binding` | Inspect credential-free repository memory destination, offline | `blop memory binding [--json]` | | `unbind` | Remove this repository memory destination without deleting knowledge | `blop memory unbind [--json]` | | `markdown` | Initialize, attach, index, list or detach a read-only local Markdown source (no model) | `blop memory markdown [folder\|attachmentId] [--project ID] [--json]` | | `context` | Read live graph context | `blop memory context [--text TEXT] [--scope local\|organization] [--profile NAME] [--project ID] [--json]` | | `search` | Read live graph search | `blop memory search [--text TEXT] [--scope local\|organization] [--profile NAME] [--project ID] [--json]` | | `get` | Read one node or bounded document section | `blop memory get [--revision N] [--field SECTION] [--body-offset N] [--body-length N] [--scope organization --profile NAME] [--json]` | | `reads` | Count which agents read which nodes (ids and counts, never content) | `blop memory reads [--project ID] [--node ID] [--agent ID] [--range 1h\|24h\|7d\|30d] [--scope organization --profile NAME] [--json]` | | `neighbors` | Read node neighbors | `blop memory neighbors [--scope organization --profile NAME] [--limit N] [--cursor CURSOR] [--json]` | | `history` | Read node history | `blop memory history [--scope organization --profile NAME] [--limit N] [--cursor CURSOR] [--json]` | | `skills` | Progressive procedure lookup: list or get | `blop memory skills [nodeId] [--document ID] [--field SECTION] [--scope organization --profile NAME] [--json]` | | `index` | Explicitly index memory with current pinned model status | `blop memory index [--scope organization --profile NAME] [--project ID] [--json]` | | `add` | Add memory with flags or a shared graph change document | `blop memory add (--kind KIND --title TEXT --body TEXT [--tags a,b] [--id namespace:name] \| --input FILE_OR_DASH) [--project ID] [--scope organization --profile NAME] [--json]` | | `patch` | Explicit patch using the shared graph change schema | `blop memory patch --input FILE_OR_DASH [--scope organization --profile NAME] [--project ID] [--idempotency-key KEY] [--expected-policy-revision N] [--json]` | | `edit` | Explicit edit using the shared graph change schema | `blop memory edit --input FILE_OR_DASH [--scope organization --profile NAME] [--project ID] [--idempotency-key KEY] [--expected-policy-revision N] [--json]` | | `batch` | Explicit batch using the shared graph change schema | `blop memory batch --input FILE_OR_DASH [--scope organization --profile NAME] [--project ID] [--idempotency-key KEY] [--expected-policy-revision N] [--json]` | | `retire` | Explicit retire using the shared graph change schema | `blop memory retire --input FILE_OR_DASH [--scope organization --profile NAME] [--project ID] [--idempotency-key KEY] [--expected-policy-revision N] [--json]` | | `restore` | Explicit restore using the shared graph change schema | `blop memory restore --input FILE_OR_DASH [--scope organization --profile NAME] [--project ID] [--idempotency-key KEY] [--expected-policy-revision N] [--json]` | | `purge` | Explicit purge using the shared graph change schema | `blop memory purge --input FILE_OR_DASH [--scope organization --profile NAME] [--project ID] [--idempotency-key KEY] [--expected-policy-revision N] [--json]` | | `propose` | Explicit propose using the shared graph change schema | `blop memory propose --input FILE_OR_DASH [--scope organization --profile NAME] [--project ID] [--idempotency-key KEY] [--expected-policy-revision N] [--json]` | | `publish` | Preview/publish one selected authored node or Markdown snapshot | `blop memory publish --profile NAME --project ID [--dry-run] [--reviewed-hash SHA256] [--json]` | | Flag | Description | Default | Environment | | --- | --- | --- | --- | | `--input ` | Finite JSON input file, or - for stdin (maximum 1 MiB) | | | | `--idempotency-key ` | Retained unique key for the exact write attempt | | | | `--expected-policy-revision ` | Reviewed live policy revision; stale revisions are rejected | | | | `--profile ` | Named origin/workspace-bound OAuth profile (default default) | default | | | `--kind ` | Kind of memory to add: entity, document, finding, decision, rule or procedure; cannot combine with --input Values: entity, document, finding, decision, rule, procedure. | | | | `--title ` | Memory title; required with --kind | | | | `--body ` | Memory body; required with --kind | | | | `--tags ` | Comma-separated tags for convenience add | | | | `--id ` | Explicit memory identity; default local: plus SHA-256 of JSON.stringify([title, body]) in UTF-8 | | | | `--scope ` | Authority plane: local or organization; overrides repository read binding; organization requires a profile Values: local, organization. | local unless bound | | | `--project ` | Explicit project ID selector (not authorization) | | | | `--limit ` | Bounded page size | | | | `--cursor ` | Opaque page cursor | | | | `--text ` | Context or search query text | | | | `--revision ` | Exact stored node revision | | | | `--document ` | Load one document explicitly referenced by the selected procedure | | | | `--field
` | Address content or complete metadata JSON without losing omitted references Values: body, whenToUse, procedure, pitfalls, verification, metadata. | | | | `--body-offset ` | Content/metadata section offset in Unicode code points | | | | `--body-length ` | Maximum section length (1–4,000 Unicode code points; byte limits may shorten it) | | | | `--reviewed-hash ` | Hash of the exact reviewed publication payload | | | | `--dry-run` | Preview exact selected content without publishing | | | | `--agent ` | Agent id recorded with this read (default $BLOP_AGENT_ID); for reads, filter by it | | | | `--session ` | Session id recorded with this read (default $BLOP_SESSION_ID) | | | | `--node ` | Only reads of this node | | | | `--range ` | Read-log window: 1h, 24h (default), 7d or 30d Values: 1h, 24h, 7d, 30d. | 24h | | ```bash blop memory context --json # Recall local knowledge without an account blop memory context --scope organization --profile team --project project-id --json # Read hosted authority explicitly blop memory reads --range 7d --json # See which agents read which memory nodes blop memory publish local:finding --profile team --project project-id --dry-run --json # Review the exact payload before sharing ``` ### blop prompts Author, version, label and fetch prompts in a local registry Local and account-free: no network, no model, no hosted authority. Prompts live in prompts.db beside the telemetry store and never change capture or retention. Versions are immutable and numbered from 1; create always moves the managed latest label. Labels start with a letter, so a label can never be read as a version, and get refuses --version together with --label. A missing prompt, version or label exits 2 with no fallback. get reports its selector's cache entry: cold (never fetched), fresh (within --cache-ttl and the same version), stale (expired, or the label moved) or disabled (--cache-ttl 0). Up to 10,000 prompts, 1,000 versions and 32 labels each; a full registry exits 4. JSON data (blop.cli/v1): list gives prompts[] of {name, version, versions, labels[{label, version}], sha256, bytes, updated_at} with page {limit, returned, truncated}; get gives name, version, selector {kind, value}, labels, content, sha256, bytes, created_at and cache {status, reason, ttl_seconds, previous_version, previous_fetched_at}; create gives name, version, labels, sha256, bytes, created_at; label gives name, label, version, previous_version. ```bash blop prompts [flags] ``` | Subcommand | Purpose | Usage | | --- | --- | --- | | `list` | List prompts, one line each, in name order | `blop prompts list [--name ] [--label