Get assets — cache-aware, runs only the needed subgraph; prints their artifact paths

If the first positional arg ends in .py, all args are treated as files (no target — gets every asset and sensor; tasks are skipped, use `barca run` for them). Otherwise, the first arg is the target asset name (or several, comma-separated: `a,b`) and the rest are files.

Each completed step writes a fully materialized artifact (never a lazy in-memory handle). If one computation should produce several cacheable outputs, define multiple assets or split the work inside a single step before returning.

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

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

Options:
  -o, --output <OUTPUT>
          What to print: artifact paths (the default) or values. Alone, -o path|value prints only that; with --json, it chooses what `final_output` holds

          Possible values:
          - path:   Artifact paths, one per line (one per selected partition key); the default
          - value:  The value, pretty-printed (a mapping of key to value for a partitioned target)
          - json:   One-line JSON, as --json
          - pretty: Summary and paths for people, as --pretty

      --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)

      --partition <KEY=VALUE[,VALUE]|JSON>
          Select keys of a partitioned target: `region=emea,amer`, or a JSON object for compound keys (`{"region": "emea", "day": "2026-10-14"}`). Only those keys are computed and returned, and --refresh of the target refreshes only them

      --refresh <REFRESH>
          Assets to force re-materialize, as ONE comma-separated list (`--refresh a,b`, not `--refresh a b`); the target itself may be named. Every asset downstream of them in the target's cone re-materializes too (see --no-cascade)

      --no-cascade
          With --refresh: re-materialize only the named assets, not what is downstream of them. Cached downstream assets then do not reflect the refresh; barca warns

      --refresh-all
          Force re-materialize EVERY asset in the target's cone (nothing comes from cache)

      --dry-run
          Show what this command would do (each step cached or will-run, and why) without executing steps or recording a run (shared history may synchronize)

      --agent
          Agent-friendly output: plain structured progress lines instead of visual progress bar

      --fields <FIELDS>
          Keep only these keys (comma-separated) on each entry of `steps` in the JSON output. Implies --json; not valid with --pretty or -o pretty. An unknown key is a usage error listing the valid ones

          [possible values: id, kind, action, status, reason, detail, run_hash, artifact, warning, artifact_mismatch, bytes_changed, elapsed_seconds, attempts, import_seconds, partitions, env]

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

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

Examples:
  BARCA_REMOTE=off barca get total pipeline.py   # local artifacts and history for this process
  barca get total                          # find `total` anywhere in the project and get it
  barca get total pipeline.py --json --fields id,status,elapsed_seconds,attempts   # timing and retries
  barca get total pipelines/               # only read files under pipelines/
  barca get                                # every asset and sensor in the project, never tasks
  barca get pipeline.py                    # every asset and sensor, never tasks; prints the last asset's path
  barca get total pipeline.py              # one target and only its upstream cone
  barca get total,orders pipeline.py       # several targets in one run; shared upstream runs once
  barca get total pipeline.py other.py     # target defined across several files
  barca get orders pipeline.py --refresh orders --json  # check recomputed artifact bytes
  barca get total pipeline.py --refresh-all        # recompute everything in that cone
  barca get total pipeline.py --refresh clean      # recompute clean and everything downstream of it
  barca get total pipeline.py --refresh clean --no-cascade   # recompute only clean
  barca get total pipeline.py --dry-run    # what would run vs come from cache; no steps execute
  barca get total pipeline.py --json       # JSON even in a terminal (the default when piped)
  barca get total pipeline.py --pretty     # summary and artifact path for humans (the default in a terminal)
  barca get total pipeline.py -o path      # only the artifact path, one per line (pipe it to xargs cat)
  barca get total pipeline.py -o value     # only the value, pretty-printed (json, parquet, CSV, pickle)
  barca get total pipeline.py -o value --json   # the JSON result with the value in final_output
  barca get sales pipeline.py              # a partitioned target: one path per key
  barca get sales pipeline.py --partition region=emea,amer   # only these keys: computed and returned
  barca get sales pipeline.py --partition region=emea --refresh sales   # recompute only that key
  barca get total pipeline.py --agent      # plain progress lines on stderr
  barca get total pipeline.py --env dev    # separate cache and state per environment
  barca list pipeline.py                   # not sure of the name? list assets and tasks first
  BARCA_OUTPUT=json barca get total pipeline.py   # env override for CI; a flag still wins
  barca get total pipeline.py --fields id,status   # JSON with each entry of `steps` trimmed to these keys

Output format: --json / --pretty, else BARCA_OUTPUT=json|pretty, else the terminal decides
(TTY -> pretty, piped -> JSON). get returns artifact paths: the pretty summary lists the path (a
small json value is previewed under it in a terminal), and in JSON final_output is the pointer
{"_barca_artifact": {"path", "format", "size_bytes"}} for every format. -o path prints only
the paths, one per line; -o value prints only the value. With --json, -o path|value choose what
final_output holds (-o path is the default). -o json|pretty are older spellings of --json|--pretty.
A partitioned target returns every key, sorted: final_output is an object keyed by partition key
("region=emea") and -o path prints one path per key. --partition region=emea,amer (or a JSON
object for compound keys) selects keys of the target: only they run, are returned and are
refreshed by --refresh. When some keys fail the run fails (exit 1) and final_output in the
failed result line holds the keys that succeeded.
JSON is one line on stdout with status ("success"), run_id,
steps_executed (0 = all cached), phases, final_output, and `steps`: what happened to each step
(ran or cached, and why; `env` holds the values of variables the node declares with env=[...],
secrets redacted). `warnings` is always an array: plan-time warnings for the steps this command
planned, [] when there are none; each is {kind, node, param, message} and is also one
`[barca] warning: ...` line on stderr. The only kind is unused_input: a step declares an input its
function never uses (barca docs assets, "Unused inputs"). Warnings never change the exit code.
--dry-run reports the same list. The Python API (barca.get) loads the value for you.
Several targets (`a,b`, comma-separated, no spaces): final_output is replaced by `targets`, keyed by
target, each {status: success, final_output} or {status: failed, failed_node, error}. Every target
runs even if another fails; exit 1 if any failed. -o path prints each target's paths in order.
Refresh: the same vocabulary as `barca run`. --refresh takes ONE comma-separated list of assets in
the cone (the target itself may be named) and also re-runs everything downstream of them;
--no-cascade re-runs only the named ones. --refresh-all re-runs every asset in the cone.
A cached step whose artifact file is gone is computed again when something needs to read it (a
step that runs takes it as an input, or it is a target), with reason `artifact_missing` and a
warning on stderr (reason `evicted` when the cache size limit deleted it). A missing artifact that
nothing reads is left alone (barca docs cache).
After the run, if .barca/ is over [cache] max_size (default 10% of the filesystem;
BARCA_CACHE_MAX_SIZE), barca evicts what is least needed down to 80% of it, never this command's
own results; stderr says what, and JSON gains `cache` (barca gc, barca docs cache "Disk use").
Completed steps are recorded during the run; remote results require confirmed upload.
Use `barca status pipeline.py` in another terminal to inspect recorded progress. Shared history
is published when the run ends (barca docs remote).
Targets must be assets; use `barca run` for tasks. With no target, get materializes every asset and
sensor and skips tasks (previously it ran tasks too); stderr names the skipped tasks and the
`barca run` command. A file with only tasks gets nothing: exit 0, empty `steps`.
The target comes before the files: `barca get pipeline.py total` exits 2 and prints
`barca get total pipeline.py`.
Errors: in JSON mode stderr contains one JSON error object {error, code, kind, remediation},
plus node, traceback and artifact_dir when a step failed. Exit 1 step failed, 2 usage error,
3 barca/infra failure, 130 cancelled. A failed step still prints a stdout result line with
status "failed" and failed_node. Stderr ends with the failed step, its first error line,
and the count of skipped downstream nodes.
A required history-write failure exits 3 and preserves previously committed history.
More: barca docs cache, barca docs partitions, barca docs types, barca docs agents
