CLI

The CLI covers local automation and scripting: it starts the server, queries stored data directly (no server required), and ingests spans and evals by hand. Examples use zig build run -- as the README does; with a prebuilt binary, call it directly instead.

Commands#

Shared flags#

Every subcommand accepts three runtime flags:

serve#

zig build run -- serve

Defaults to 127.0.0.1:7710. To bind elsewhere:

zig build run -- serve --host 0.0.0.0 --port 7710

--host and --port exist only on serve; the shared flags work here too.

Query commands#

All query commands read the local JSONL store under ~/.nullwatch/data; the server does not need to be running.

zig build run -- summary
zig build run -- runs --verdict pass --limit 20
zig build run -- spans --source nullclaw --tool-name shell --limit 50
zig build run -- evals --dataset prod-shadow --verdict fail
zig build run -- run run-123

Ingest commands#

Both take a single JSON document via --json. Field meanings are in the data model.

zig build run -- ingest-span --json '{
  "run_id": "run-123",
  "trace_id": "trace-123",
  "span_id": "span-1",
  "source": "nullclaw",
  "operation": "model.call",
  "status": "ok",
  "started_at_ms": 1710000000000,
  "ended_at_ms": 1710000000320,
  "model": "gpt-5",
  "prompt_version": "reply-v3",
  "input_tokens": 420,
  "output_tokens": 96,
  "cost_usd": 0.018
}'

zig build run -- ingest-eval --json '{
  "run_id": "run-123",
  "eval_key": "helpfulness",
  "scorer": "llm-judge",
  "score": 0.94,
  "verdict": "pass",
  "dataset": "prod-shadow"
}'

demo-seed#

zig build run -- demo-seed

Creates a deterministic demo dataset of 3 runs (11 spans, 3 evals): a passing code-review run, a failed tool-call run, and a handoff/retry run with checkpoint context. No API keys, no hosted services, no agent workload. Seeding is idempotent — a second run skips all three existing run ids (runs_skipped: 3) and creates nothing. Useful for demos, manual testing, and trying the NullHub Observability page against real-shaped data:

zig build run -- demo-seed
zig build run -- runs --limit 20
zig build run -- run demo-tool-failure

NullHub integration flags#

NullWatch stays headless; these two flags let NullHub own installation and setup. Each must be the first argument — they are commands, not modifiers. --export-manifest prints a JSON manifest with platform assets, ports and a 4-step setup-wizard schema; --from-json writes ~/.nullwatch/config.json from the wizard's answers:

# print the nullhub manifest describing this component
zig build run -- --export-manifest

# write config from wizard answers
zig build run -- --from-json '{"home":"~/.nullwatch","port":7710,"data_dir":"data"}'

The --from-json payload also accepts host and api_token, matching the config file fields.

Environment#