Inspect persisted observation-store runs and artifacts.

Synopsis

homeboy runs list [--kind bench|rig|trace] [--component <id>] [--rig <id>] [--status <status>] [--limit 20]
homeboy runs distribution --field <metadata.path> [--kind bench] [--component <id>] [--rig <id>] [--scenario <id>] [--status <status>] [--limit 20]
homeboy runs compare [--kind bench] [--component <id>] [--rig <id>] [--scenario <id>] [--metric <name>] [--limit 20] [--format table|json]
homeboy runs show <run-id>
homeboy runs artifacts <run-id>
homeboy runs export --run <run-id> --output <dir>
homeboy runs export --since <duration> --output <dir>
homeboy runs import <dir>

Description

homeboy runs is a read-only query surface over Homeboy’s local observation store. Producers such as bench, rig, and trace write run and artifact records; this command lets humans and agents inspect that evidence without opening SQLite directly.

The JSON output includes stable run fields: run id, kind, status, timestamps, component id, rig id, git SHA, command, cwd, metadata, and artifact records where relevant.

homeboy runs distribution aggregates categorical values from dot-separated JSON metadata paths. Scalar string, number, and boolean values are counted directly; arrays are flattened and counted by scalar element. The output reports inspected runs, matched/missing runs per field, total and unique value counts, value percentages, and repeated values.

Compare Metrics Across History

homeboy runs compare compares selected persisted metrics across recent observation runs. It defaults to benchmark history and the total_elapsed_ms metric:

homeboy runs compare --kind bench --component studio --metric total_elapsed_ms --limit 20
homeboy runs compare --kind bench --component studio --rig studio-bfb --scenario studio-agent-site-build --metric total_elapsed_ms --metric p95_ms

The default output is a Markdown table with run id, status, start time, git SHA, rig id, artifact count, scenario, and selected metric columns. Use --format=json for structured output, or pair it with global --output <file> to write command JSON to disk:

homeboy runs compare --kind bench --component studio --metric total_elapsed_ms --format=json --output runs-compare.json

Metric lookup supports top-level run metadata such as results.total_elapsed_ms, direct dotted paths, and benchmark scenario metrics recorded under scenario_metrics[].metrics or metric_groups.

Related Readers

homeboy bench history <component> [--scenario <id>] [--rig <id>] [--limit 20]
homeboy bench distribution <component> --field <metadata.path> [--scenario <id>] [--rig <id>] [--status <status>] [--limit 20]
homeboy bench compare --from-run <run-id> --to-run <run-id>
homeboy rig runs <id> [--limit 20]

These commands are thin read-only wrappers over the same observation-store records.

Portable Bundles

homeboy runs export writes an inspectable directory bundle for moving observation evidence between machines without copying raw SQLite:

homeboy-observations/
  manifest.json
  runs.json
  artifacts.json
  trace_spans.json
  findings.json
  test_failures.json

The v1 bundle is metadata-only: artifact records are exported, but artifact file bytes are not copied. findings.json contains normalized observation findings, and test_failures.json is an additive subset of findings where test commands recorded individual failures. Zip output is intentionally out of scope for v1; pass a directory path to --output.

homeboy runs import is idempotent. Existing identical records are accepted, while conflicting records with the same primary key fail clearly.