CLI Reference

Every verb. Every flag. Every exit code. Authored against the v0.6.0 release.

bl is a single bash script (~10,700 lines) assembled from 26 numbered parts under src/bl.d/ via make bl. Nine top-level verbs dispatch from main() in 90-main.sh. Every verb except setup and --help/--version runs bl_preflight before the verb body.

This page is the canonical reference. For why the surface looks like this, see Architecture. For how to configure the runtime, see Configuration.

At a glance

Global conventions

• Help bypass. bl -h | --help | help and bl <verb> --help both bypass preflight. bl setup --help works on an unseeded host.
• Version. bl -v | --version prints bl 0.5.0.
• JSONL on the wire. Every bl observe collector emits one record per line. See Evidence Format.
• Tier authorship. The agent classifies every step in bl-case/<case>/pending/<id>.json. The Runner enforces the gate based on verb class plus tier — verb class always wins. clean.* is always destructive regardless of agent-asserted tier.
• Schema validation. bl run validates the step JSON against schemas/step.json before executing.
• BL_DISABLE_LLM=1 short-circuits every LLM call across the surface. The full BATS suite exports this.

Exit codes

POSIX 1–63 reserved by convention; 73–79 reserved for future blacklight use; 80–127 unused; 128+ are signal-based exits inherited from bash.

Tier matrix

Every bl observe, bl consult, and bl case show/log/list is read-only by verb class. Every bl clean is destructive regardless of agent-asserted tier (verb class re-asserts). bl defend and bl run flow through the agent's action_tier field. See Action Tiers for the full matrix.

---

bl observe

Read-only evidence extraction. Auto-runs (no confirm). Emits JSONL to stdout and appends structured output to the current case bundle.

Synopsis

bl observe <subcommand> [args] [flags]

Sub-commands

Common flags

Examples

# Time-window slice around a suspicious file
$ bl observe log apache --around /var/www/html/pub/media/catalog/product/.cache/a.php --window 6h

# Retrospective fleet sweep against APSB25-94 disclosure date
$ bl observe fs --mtime-since 2026-03-20T00:00:00Z --under /var/www/html --ext php

# Bundle everything collected on this host into a tar+gzip evidence pack
$ bl observe bundle

Tier

Read-only. Auto-execute. No confirm prompt.

Exit codes

0, 64 (bad args), 65 (preflight), 66 (workspace unseeded).

See also

• bl consult --new to open a case anchored on the observation.
• Evidence Format — JSONL contract, bundle shape.

---

bl consult

Case lifecycle: open a new case or attach the operator shell to an existing one. Wakes the curator session.

Synopsis

bl consult --new --trigger <path-or-event> [--notes "..."] [--dedup]
bl consult --attach <case-id>
bl consult --sweep-mode [--cve <id>]

Modes

Flags

Examples

# Open a fresh case from a polyshell artifact
$ bl consult --new --trigger /var/www/html/pub/media/catalog/product/.cache/a.php
CASE-2026-0017

# Attach the shell to an existing case (sets case.current)
$ bl consult --attach CASE-2026-0017

# Retrospective sweep across closed cases for a specific CVE
$ bl consult --sweep-mode --cve APSB25-94

Tier

Read-only. No host mutation. Wakes the curator session.

Exit codes

0, 64, 65, 66, 69 (upstream), 70 (rate limit), 71 (case allocation collision after 50 retries), 72 (--attach target missing).

See also

• bl run --list — surface the steps the curator emitted.
• bl trigger lmd — case open from a hook-fired event.

---

bl run

Execute an agent-prescribed step under tier-gated safety.

Synopsis

bl run <step-id> [--yes] [--dry-run] [--unsafe] [--explain]
bl run --list
bl run --batch [--max <N>] [--yes]

Modes

Flags

Examples

# Show the queue
$ bl run --list
s-0001  observe.modsec       read-only      confirm rule coverage before payload
s-0043  defend.modsec        suggested      polyshell double-ext staging
s-0044  clean.cron --user x  destructive    strip ANSI-obscured cron entry

# Auto-execute a read-only step
$ bl run s-0001

# Explicit-yes on a suggested ModSec rule
$ bl run s-0043 --yes

# Drain the queue (auto + read-only auto-run; suggested honours --yes)
$ bl run --batch --max 8 --yes

Tier

Delegated. The step's action_tier field controls the gate. The Runner re-asserts on verb class — clean.* is always destructive, unknown verbs always deny.

Exit codes

0, 64, 65, 66, 67 (schema fail), 68 (tier gate denied / unknown verb), 69, 70, 72 (step-id not in pending).

See also

• Action Tiers — full gate matrix.
• bl consult --new — what populates the pending queue.

---

bl defend

Apply an agent-authored defensive payload. Three families: ModSec rules, firewall blocks, scanner signatures.

Synopsis

bl defend modsec <rule-file-or-id> [--remove] [--rollback <event-id>]
bl defend firewall <ip> [--backend auto] [--case <id>] [--reason <str>] [--retire <duration>]
bl defend sig <sig-file> [--scanner lmd|clamav|yara|all]

Sub-commands

Flags

Examples

# Apply a curator-authored ModSec rule (passes apachectl -t in sandbox first)
$ bl defend modsec /tmp/bl-CASE-2026-0017-941999.conf --yes

# Block an attacker IP with a 30d retire hint
$ bl defend firewall 203.0.113.42 --reason "polyshell campaign C2" --retire 30d

# Promote a curator-authored YARA sig (deterministic FP gate + Haiku adjudication)
$ bl defend sig /tmp/bl-polyshell-double-ext.yar --scanner yara

Tier

• auto — defend firewall <ip> (new block; CDN safe-listed); defend sig after FP gate passes.
• suggested — defend modsec (new rule).
• destructive — defend modsec --remove.

Exit codes

0, 64, 65, 66, 67, 68, 69, 70, 72.

See also

• Action Tiers — auto vs suggested vs destructive policy.
• Security Model · CDN safe-list — firewall guard rails.

---

bl clean

Diff-confirmed remediation. Backup before apply. Quarantine, never unlink. --undo round-trips.

Synopsis

bl clean htaccess <dir> [--patch <file>] [--dry-run]
bl clean cron --user <user> [--patch <file>] [--dry-run]
bl clean proc <pid> [--capture] [--dry-run]
bl clean file <path> [--reason <str>] [--dry-run]
bl clean --undo <backup-id>
bl clean --unquarantine <entry-id>

Sub-commands

Flags

Diff prompt

For file-edit subcommands the prompt offers [y/N/diff-full/explain/abort]:

• y — apply.
• N — cancel; mark step operator-rejected (the curator sees this).
• diff-full — show the whole before/after.
• explain — dump the curator's reasoning field.
• abort — cancel and emit a session warning until the case closes.

Examples

# Strip an injected FilesMatch block; diff shown, backup written
$ bl clean htaccess /home/sitefoo/public_html --yes

# Remove the entire cron entry an attacker hid via ANSI escape
$ bl clean cron --user sitefoo --yes

# Capture /proc state then SIGTERM → SIGKILL the process
$ bl clean proc 31415

# Quarantine a polyshell sample (file moves to /var/lib/bl/quarantine/<case>/)
$ bl clean file /var/www/html/.cache/a.php --reason "polyshell APSB25-94"

# Roll back a clean operation
$ bl clean --undo 2026-04-26T04-27-15Z.htaccess

Tier

Always destructive by verb class. Agent-asserted tier is ignored. Backup written before every apply; quarantine-not-delete enforced for clean file.

Exit codes

0, 64, 65, 66, 67, 68, 72.

See also

• Security Model · Filesystem safety — TOCTOU rationale.
• Action Tiers · Destructive — full discipline.

---

bl case

Inspect / log / close / reopen. Cases are allocated by bl consult --new — there is no bl case open.

Synopsis

bl case list [--open|--closed|--all]
bl case show [<case-id>]
bl case log [<case-id>] [--audit]
bl case close [<case-id>] [--force]
bl case reopen <case-id> --reason <str>

Sub-commands

Flags

Examples

# List open cases on this host
$ bl case list --open

# Six-section summary of the current case
$ bl case show

# Audit-format ledger for a regulator
$ bl case log CASE-2026-0017 --audit

# Close after the curator confirms open_questions = 0
$ bl case close

# Reopen with a documented reason
$ bl case reopen CASE-2026-0017 --reason "T+5d sweep showed re-pivot"

Tier

list / show / log are read-only. close is destructive (writes the brief, schedules retires). reopen is suggested.

Exit codes

0, 64, 65, 66, 68, 69, 70, 72.

See also

• bl consult --new — case allocation.
• Architecture · State model — bl-case memstore layout.

---

bl setup

Workspace bootstrap. Idempotent. Preflight is bypassed (setup carries its own local preflight).

Synopsis

bl setup --sync [--dry-run]
bl setup --reset [--force]
bl setup --gc
bl setup --eval [--promote]
bl setup --check
bl setup --install-hook lmd
bl setup --import-from-lmd

Sub-commands

Flags

Live-API contract (M15)

• Agent update: POST /v1/agents/<id> with {version: <current>, ...}. PATCH returns 405. On 409 the client refetches and retries once.
• Agent retire: POST /v1/agents/<id>/archive. DELETE returns 405. Empty {} body. --reset aborts if archive fails — never wipe state.json while a live agent exists.
• Sessions.create body: {agent: <id>, environment_id: <id>, resources: [...]}. The field is agent, not agent_id.
• Environments body: {name, config:{type:"cloud", networking:{type:"unrestricted"}}} only. No packages, setup_script, or image field.

Examples

# First-run on a fresh workspace (or no-op on a seeded one)
$ export ANTHROPIC_API_KEY="sk-ant-..."
$ bl setup --sync

# Idempotent re-sync after editing skills
$ bl setup --sync

# Wipe everything except case audit trail
$ bl setup --reset --force

# Wire LMD's post_scan_hook to bl trigger
$ bl setup --install-hook lmd

Tier

Preflight bypass. --sync and --gc are non-destructive at workspace scope; --reset requires --force.

Exit codes

0, 64, 65, 66 is impossible (this is the verb that seeds it), 67, 69, 70, 71 (CAS conflict, retried internally).

See also

• Setup Flow — full call-by-call API contract.
• Anthropic API Notes — the friction this verb routes around.

---

bl trigger

Hook-fired case open from existing trigger surfaces. Today: LMD post_scan_hook.

Synopsis

bl trigger lmd --scanid <id> [--session-file <path>] [--source-conf <path>] [--unattended]

Sub-commands

Flags

Examples

# Manual replay of an LMD hook-fire (LMD itself calls this from post_scan_hook)
$ bl trigger lmd --scanid 250426-141520.31415

# Force unattended (queue tier-gated steps for operator instead of prompting)
$ bl trigger lmd --scanid 250426-141520.31415 --unattended

Tier

Read-only at the trigger layer. The case it opens may emit destructive steps; the gate catches those at bl run time, not here.

Exit codes

0, 64, 65, 66, 69, 70.

See also

• bl setup --install-hook lmd — wire the maldet post_scan_hook= line.
• bl consult --new --dedup — the dedup mode this verb uses.

---

bl flush

Drain queued outbox records (wake / signal_upload / action_mirror). Idempotent. Safe from cron.

Synopsis

bl flush --outbox

Flags

Drain policy

Preflight runs an age-gated drain automatically when the oldest queued record is ≥ BL_OUTBOX_AGE_WARN_SECS (default 3600). bl flush --outbox forces a drain regardless of age — useful from cron, useful when chasing a queued record.

Watermarks: warn at 500 records, hard-stop at 1000 (returns BL_EX_RATE_LIMITED=70). The cycle-break invariant in 27-outbox.sh keeps the queue's own backpressure-reject record from re-entering the ledger via the outbox path.

Examples

# Drain manually
$ bl flush --outbox

# From cron, every 15 minutes
*/15 * * * * /usr/local/bin/bl flush --outbox

Tier

Read-only at the verb level. The outbox replay re-issues network calls that may individually mutate workspace state (those are tier-checked at write time).

Exit codes

0, 64, 65, 69, 70.

See also

• Configuration · BL_OUTBOX_AGE_WARN_SECS — drain threshold.
• Architecture · Rate limiting — outbox's role.

---

Bash SDK

bl is built as a bash SDK that the CLI dispatcher consumes. Sourcing the assembled binary (source bl || true) exposes 137 bl_* functions across 14 families. Stable surfaces: bl_api_*, bl_files_*, bl_skills_*, bl_ledger_*, bl_outbox_*, bl_fence_*, bl_messages_call, bl_notify. Internal: everything else; subject to rename at any milestone.

Operators consuming the SDK should pin to a specific tagged version of bl. Full surface enumeration in Architecture · Bash SDK.

---

See also

• Configuration — env vars, state.json, /var/lib/bl/, /etc/blacklight/blacklight.conf.
• Architecture — three-layer contract, runtime flow, SDK surface.
• Setup Flow — endpoint-by-endpoint contract for bl setup --sync.
• Action Tiers — gate matrix for bl run / bl defend / bl clean.
• Security Model — what the gate catches.