Show every node's cache state, last materialization and artifact shape (read-only)

One aggregated view: what `barca list`, `--dry-run`, `barca history` and a look inside the artifact would each tell you. If the first positional arg ends in .py, all args are files; otherwise the first is a target (or several, comma-separated: `a,b`) and only the upstream cones of the targets are shown.

Usage: barca status [OPTIONS] [ARGS]...

Arguments:
  [ARGS]...
          [TARGET[,TARGET...]] [file.py|dir/ ...] — both optional; no files reads the whole project (`barca docs discovery`)

Options:
      --json
          Emit JSON on stdout (the default when stdout is not a terminal)

      --pretty
          Emit human-readable output (the default when stdout is a terminal)

  -l, --limit <LIMIT>
          Maximum nodes, in topological order (default: every node in JSON, 100 in a human table)

      --all
          Show every node (no limit)

      --fields <FIELDS>
          Output JSON with only these keys (comma-separated) on each entry of `nodes`. Implies --json. An unknown key is a usage error listing the valid ones

          [possible values: id, name, kind, inputs, partitioned, cache, partitions, last_materialization, last_bytes_change, shape, env, undeclared_env, local, schedule]

      --sample <N>
          Include up to N sample rows from each json/parquet/CSV artifact (off by default; pickles are never sampled)

      --state <STATE>
          Show only nodes in these cache states (comma-separated): cached, unsynced, stale, never_run, partial, unknown, always_runs. The summary still counts every node

      --problems
          Show only nodes that need attention: not cached (unsynced, stale, never_run, partial, unknown), a task or sensor whose last run failed, or a paused or failing schedule

      --env <ENV>
          Environment name (separates cache/state per environment)

      --server [<URL>]
          Run this command on a barca server (`barca serve`) and print its result here: the URL given, or with no URL the configured one (BARCA_SERVER, else [server] url in barca.toml). Without it, get and run run on this machine (against a configured server's ledger), status, history, stats and logs are answered by a configured server, and sql resolves its views from it (the query always runs here)

      --local
          Ignore any configured server for this command: run against this machine's own ledger and records; nothing is read from or sent to the server

  -h, --help
          Print help (see a summary with '-h')

Examples:
  barca status                             # every node in the project
  barca status pipeline.py                 # table in a terminal (JSON when piped): kind, cache state, last run, shape
  barca status total pipeline.py           # only `total` and its upstream cone
  barca status total,orders pipeline.py    # several targets: the union of their cones
  barca status pipeline.py --json          # {target, targets, nodes, summary, total, truncated, root}, even in a terminal
  barca status pipeline.py --pretty        # the table, even when piped
  barca status pipeline.py --fields id,cache   # JSON with only these keys per node
  barca status big.py --limit 20           # first 20 nodes; the summary counts all
  barca status total pipeline.py --json --sample 5   # add up to 5 sample rows per json/parquet/CSV artifact
  barca status pipeline.py --env dev       # state recorded in another environment
  barca status total --server              # cache state on the configured barca server
  barca status total --json                # with a server configured: its ledger, plus `local` per node
  barca status total --local               # this machine's own state, even with a server configured
  barca status --problems                  # only nodes that need attention: not cached, a failed run, a paused or failing schedule
  barca status --state stale,never_run     # only nodes in these cache states; the summary still counts every node
  barca status --problems --server         # what needs attention on the configured server

Cache state per node: cached, unsynced (cached here, its upload to the artifact store still
pending: reason `local_only`), stale (ran before; code or inputs changed, or its artifact file is
gone and a run would read it: reason `artifact_missing`, or `evicted` when the cache size limit
deleted it), never_run, partial
(some partition keys cached), unknown (dynamic partitions not yet known) or always_runs (tasks,
sensors), with a reason. JSON spells the states in snake_case, the same as the `summary` keys
(the table prints never-run, always-runs). It is the same decision `--dry-run` makes.
With a server configured (BARCA_SERVER, [server] url) and no --local, the server answers, each
node gets `local` (a copy is here), and a result computed here whose ledger post is pending is
unsynced: reason `not_in_ledger` (barca docs server-mode).
No steps execute; nothing is written. partitions(<expression>) may import the source to resolve
keys. With a store, a cached node is `unsynced` unless this machine's copy, the store's object and
the recorded digest agree: reason `local_only`, `store_only` or `mismatch` (barca docs remote). Shape (rows, columns, type) is read from the
artifact file only. With remote storage it is read from the bucket: a parquet footer by ranged
requests, json and pickle by a download of up to 16 MB (larger ones get a `note`). A store that
cannot be reached is a `note` on each shape, not a failed command.
--problems keeps the nodes that need attention: every state but cached and always_runs, a task
or sensor whose last run failed, and a schedule that is paused or failing (max_failures reached).
--state keeps the named states. Either way the summary counts every node, and the JSON says
which filter applied in `filter`. A failed node's error is `last_materialization.error`, and its
first line is in the WHY column. A scheduled node has `schedule` (cron, next fire, failures,
paused): from a server, its scheduler's view; on this machine, what the metadata DB holds.
JSON returns every item unless --limit is given; human tables keep their default bound.
More: barca docs status, barca docs agents
