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

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

Arguments:
  [ARGS]...
          Target(s), then optional files/directories; omit files to discover the project

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>
          Select JSON fields as a comma-separated list; implies --json

          [possible values: id, name, kind, inputs, partitioned, cache, health, health_reason, signals, measured, cause, root, gap_seconds, last_check, refresh_path, stale_since, expected_fresh_at, recheck_at, no_estimate, last_attempt, typical_run_seconds, 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, blocked, unknown, always_runs. The summary still counts every node. With --keys: only keys in these key states: failed, blocked, stale, never_run, pinned, fresh

      --cause <CAUSE>
          Keep nodes with this cause

          [possible values: failing, overdue, no_refresh_path, queued, undecided, catching_up]

      --health <HEALTH>
          Keep nodes with this health

          [possible values: failing, blocked, suspect, behind, undecided, never_run, ok]

      --root <ROOT>
          Keep nodes with this root id

      --problems
          List problems by distance from fresh; omit work already in hand unless selected by cause

      --rollup
          Experimental: print the rollup instead of the nodes: counts by cause per group and file, in nodes and in assets, then what holds the nodes that are not fresh (the ranked roots) and the action that clears each

      --now
          Evaluate the rollup at the current second (server polls default to the minute)

      --keys
          Experimental: list the keys of one partitioned target, each with its state

      --needs-run
          Experimental, with --keys: only keys a run computes

      --value <DIM=VALUE[,VALUE]>
          Experimental, with --keys: only keys with these values of a dimension

      --range <DIM=FROM..TO>
          Experimental, with --keys: only keys in a stretch of a dimension

      --error <N>
          Experimental, with --keys: only the failed keys of error group N

      --match <TEXT>
          Experimental, with --keys: only keys that contain TEXT

      --sort <ORDER>
          Experimental, with --keys: order by key, state, attempted, elapsed, size or rows

          [possible values: key, state, attempted, elapsed, size, rows]

      --offset <N>
          Experimental, with --keys: skip the first N matching keys

      --overview
          Experimental: print one partitioned target's keys in one picture: counts, issues, rows

      --grid
          Experimental: print one partitioned target's keys as a grid of states

      --key <KEY>
          Experimental: show one key (day=2026-01-01,region=apac) of one partitioned target

      --env <ENV>
          Use a separate cache and history for this environment

      --server [<URL>]
          Use a server (URL or configured); get/run execute its deployed code

      --local
          Run on this machine; ignore a configured server and this project's barca serve

  -h, --help
          Show concise command help

      --examples
          Show all command examples without running anything

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, as_of, rollup, 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 scored pipeline.py --json   # partitions.changed: why each missing key will run
  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 --cause overdue             # nodes whose ticks did not leave them fresh
  barca status --health behind             # nodes classified behind
  barca status --root failure:pipeline.py:source  # nodes held by this failure
  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
  barca status --rollup --now --server     # evaluate the deployed graph at the current second
  barca status --rollup                    # counts by cause per group and file, then what holds the nodes that are not fresh and what clears each
  barca status --rollup --json             # {as_of, entries, roots, data_coverage}: what GET /state/rollup answers
  barca status --json --fields id,health,cause,root,gap_seconds   # why each node is not fresh, and what explains it
  barca status total --rollup --server     # the rollup of `total` and its upstream cone on the configured server
  barca status scored --keys               # every key of a partitioned node: state, last attempt, rows, error
  barca status scored --keys --state failed,blocked --json   # {id, known, dimensions, counts, errors, keys, total, truncated, offset, needs_run, selection}
  barca status scored --keys --limit 20    # the first 20 keys; a note says how many there are
  barca status scored --keys --limit 20 --offset 20   # the next 20
  barca status scored --keys --needs-run   # only the keys a run computes: failed, blocked, stale, never run
  barca status scored --keys --value region=apac,emea   # only these values of a dimension; repeat for another
  barca status scored --keys --range day=2026-01-01..2026-01-31   # a stretch of a dimension, in its order
  barca status scored --keys --state failed --error 0   # the failed keys of the most common error
  barca status scored --keys --match 2026-03   # keys that contain the text
  barca status scored --keys --sort attempted --limit 10   # the 10 keys attempted last
  barca status scored --overview           # counts, what is wrong and where, and the grid's rows
  barca status scored --overview --json    # {id, chain, known, dimensions, counts, needs_run, errors, issues, along, rows, ...}
  barca status scored --grid               # every key's state, one character each, a row per value of the shorter dimensions
  barca status scored --grid --json        # the whole grid in columns: what GET /assets/{name}/partitions/grid answers
  barca status scored --key region=apac    # one key: its state along its chain, its attempts, what it wrote and read
  barca status scored --key day=2026-01-01,region=apac --sample 5 --json   # what GET /assets/{name}/partitions/key answers
  barca status scored --keys --state failed --server   # the same list from the configured server

More: barca docs status, barca docs partitions, barca docs agents
