# Runs Command

Inspect persisted observation-store runs and artifacts.

## Synopsis

```bash
homeboy runs list [--runner <runner-id>] [--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 artifact cleanup-downloads [--runner <runner-id>] [--run-id <run-id>] [--apply]
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.

`homeboy runs list --runner <runner-id>` queries a connected runner daemon instead of the local observation store, preserving the normal `runs.list` JSON payload while returning evidence from the runner machine.

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 artifact cleanup-downloads` plans cleanup for local runner artifact downloads under Homeboy's artifact root (`<artifact-root>/runner`). By default it is a dry run; pass `--apply` to remove the planned cache subtree. Use `--runner` and `--run-id` to narrow cleanup to a specific runner or run cache.

`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:

```bash
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:

```bash
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

```bash
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:

```text
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.
