CLI reference

python3 -m shadowclaw [OPTIONS]

An installed .pkg also provides /usr/local/bin/shadowclaw, which takes the same arguments.

Sensor options

Flag	Effect
--config PATH	Path to shadowclaw.json. A file named here must exist.
--interval SECONDS	Override the sample interval.
--duration SECONDS	Stop after this many seconds.
--cycles COUNT	Stop after this many polls.
--min-risk SCORE	Override the minimum risk score to report.
--otlp-endpoint URL	Override the OTLP/HTTP base URL.
--no-otlp	Do not export to the collector at all.
--no-otlp-metrics	Export findings but not metrics. Required for Loki-direct.
--no-preflight	Skip the advisory startup checks.
--no-file	Do not append findings to disk.
--no-ledger	Do not write the durable local ledger. You almost never want this.
--dns-sniffer	Enable the tcpdump DNS sniffer. Requires root.
--esf	Enable the Endpoint Security event source. Requires root, and Full Disk Access on some builds.
--no-esf	Disable Endpoint Security even if the config enables it.
--verbose, -v	Log a line per poll.

Inspection and exit

These do their work and exit rather than starting the loop.

Flag	Effect
--self-test	Check platform capability, host tooling, Endpoint Security admission, and take a live acquisition sample.
--verify	Run the 31-scenario detection matrix against synthetic samples.
--show-catalog	Print the provider catalog.
--about	Print authorship and attribution details, including the digest comparison.
--version	Print the version.

The local ledger

--ledger takes an optional action rather than being a subcommand.

python3 -m shadowclaw --ledger [view|events|verify|export|path|watch]

Action	Effect
view (default)	Readable episode summary.
events	Raw event JSON, newest first.
verify	Check the hash chain and report the first break by sequence number.
export	Write a report in CSV, JSON, or HTML.
path	Print every output location — ledger, JSONL, findings, KTP files.
watch	Follow the raw stream live, one plain-English line per change.

Ledger options

Flag	Default	Applies to
--format {csv,json,html}	csv	export
--since DURATION	—	all; watch backfills 5m
--limit COUNT	50	view, events
--ledger-dir PATH	auto	all
--out PATH	stdout	export
--no-follow	—	watch — render the window and exit
--heartbeat SECONDS	60.0	watch — still-active lines for a long episode
--poll SECONDS	1.0	watch — how often to check for new records

--since accepts 30m, 24h, 7d and similar.

python3 -m shadowclaw --ledger --since 7d --limit 200
python3 -m shadowclaw --ledger export --format html --out report.html
python3 -m shadowclaw --ledger watch --since 1h

Readers never contend with the writer

--ledger watch tails ledger.jsonl and does not claim the sensor.owner marker, so a viewer is never mistaken for a competing sensor. See Startup checks.

Helper scripts

scripts/install.sh

Flag	Effect
--check	Report prerequisites and exit.
--with-otelcol	Also download and verify the OpenTelemetry Collector.
--skip-otelcol	Compatibility no-op.

scripts/ShadowclawAI

Lifecycle for the full local stack — Loki, Grafana, and the sensor.

bash scripts/ShadowclawAI start|stop|status|restart

Configured by SHADOWCLAW_O11Y_DIR, SHADOWCLAW_ESF, SHADOWCLAW_DNS_SNIFFER, SHADOWCLAW_SENSOR_ARGS, and PYTHON. See Quickstart.

scripts/uninstall.sh

Flag	Effect
--dry-run	Print the plan; change nothing.
--yes, -y	Skip the typed confirmation.
--purge-evidence	Also delete the ledger and /etc/shadowclaw.
--keep-o11y	Leave ~/.shadowclaw-o11y in place.
--remove-otelcol	Also delete bin/otelcol from the checkout.
--grafana-url URL	Clean the dashboard out of a Grafana we did not install.
--grafana-token TOKEN	Credential for that Grafana.

See Uninstall.

scripts/coordinated-test.py

Scores a run against ground truth you declare first.

Flag	Effect
--expect PROVIDERS	Required. Comma-separated ids, names, domains, or aliases.
--duration SECONDS	How long to observe.
--config PATH	Sensor config to use.
--min-risk SCORE	Reporting threshold for the run.
--ledger-dir PATH	Where to read the durable record from.
--swarm COMMAND	Command that generates the traffic, instead of doing it by hand.
--report PATH	Write the scorecard to a file.

See Verification.

Other scripts

Script	Purpose
scripts/run-sensor.sh	Python entrypoint wrapper. Passes all arguments through.
scripts/run-collector.sh	Validate the config and start the Collector.
scripts/install-otelcol.sh	Verified contrib Collector download.
scripts/demo.sh	Local model stub + rogue agent + sensor.
scripts/esf-volume-spike.py	Measure raw and prefiltered Endpoint Security event volume. --seconds N.
scripts/add-agentic-panels.py	Idempotent Grafana dashboard migration.

Simulators

Simulator	Flags
simulators/rogue_agent.py	--iterations, --burn, --hold, --sleep, --only, --no-network, --no-burn
simulators/local_runner_sim.py	--port, --burn, --idle-burn

--iterations 0 runs until interrupted.

Make targets

make help lists all 24.

Target	Runs
install, install-check	scripts/install.sh, with and without --check.
otelcol	Download the Collector.
test	The unit suite — 983 test methods across 33 files.
verify	The 31-scenario detection matrix.
selftest, about, catalog	The corresponding sensor flags.
validate	Validate the Collector config.
collector, sensor	Start each component.
rogue, runner, demo	The simulators and the full demo.
coordinated-test	Wraps coordinated-test.py. Takes EXPECT=.
ledger, watch, ledger-verify, ledger-report	The common ledger actions.
pkg, pkg-verify	Build and verify the macOS installer.
clean, distclean	Remove build and data artefacts. Never the ledger — that lives outside the tree.

make coordinated-test EXPECT=openai,groq

The KTP oracle sidecar

Separately versioned, and explicitly not part of the sensor. Needs Python 3.11+.

python3 -m ktp_oracle --ledger PATH [OPTIONS]

Flag	Effect
--ledger PATH	Where to read Risk Factor JSONL from.
--profile PATH	Deployment profile.
--issuer URI, --subject URI	Trust Proof identity.
--e-base 0..100	Base environmental score.
--follow / --once	Tail, or evaluate a single window.

See The optional oracle.

Next

ConfigurationThe file behind most of these flags.

The local ledgerWhat the six ledger actions are reading.

Verification--verify and the coordinated test in detail.