Run a task and its dependency cone — the task always re-runs

The task always re-runs. Upstream assets are served from cache when fresh (same as `barca get`). Use `--refresh` to force re-materialize specific upstream assets, or `--refresh-all` to refresh the entire upstream cone.

Usage: barca run [OPTIONS] <ARGS>...

Arguments:
  <ARGS>...
          TARGET[,TARGET...] [file.py|dir/ ...] — one or more target tasks, comma-separated; no files reads the whole project (`barca docs discovery`)

Options:
      --refresh <REFRESH>
          Upstream assets to force re-materialize, as ONE comma-separated list (`--refresh a,b`, not `--refresh a b`). Every asset downstream of them in the task'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 task'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)

  -o, --output <OUTPUT>
          Output format (kept for compatibility; --json / --pretty are the canonical spelling)

          Possible values:
          - json:   One-line JSON (default when stdout is not a terminal)
          - value:  Just the final_output value, pretty-printed
          - pretty: Human-friendly with timing info (default when stdout is a terminal)

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

      --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. Not valid with -o value/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 run deploy pipeline.py   # local artifacts and history for this process
  barca run deploy                                     # find the task anywhere in the project and run it
  barca run deploy pipelines/                          # only read files under pipelines/
  barca run deploy pipeline.py                         # task runs; upstream assets come from cache
  barca run deploy pipeline.py --refresh fetch,clean   # re-materialize these and everything downstream of them
  barca run deploy pipeline.py --refresh fetch --no-cascade   # re-materialize only fetch; downstream stays cached
  barca run deploy pipeline.py --refresh-all           # re-materialize every upstream asset
  barca run deploy pipeline.py --dry-run --refresh fetch   # preview: which steps run, which are cached
  barca run deploy pipeline.py --json                  # JSON even in a terminal (the default when piped)
  barca run deploy pipeline.py --pretty                # summary for humans (the default in a terminal)
  barca run deploy pipeline.py --fields id,status,reason   # JSON with each entry of `steps` trimmed
  barca run check_a,check_b pipeline.py                # several tasks in one run; shared upstream runs once
  barca run check_a,check_b pipeline.py --dry-run      # preview the union of both cones
  barca list pipeline.py                               # not sure of the name? list assets and tasks first

Several targets: comma-separated, no spaces. Every target runs even if another fails (a failure
skips only what depends on it); exit 1 if any failed. JSON output then carries `targets`, keyed by
target, instead of `final_output` (see barca get --help, barca docs agents).
`warnings` is always an array, as on `barca get`: plan-time warnings for the steps in the cone, such
as an input a step never uses (barca docs assets); [] when there are none.

--refresh takes ONE comma-separated list (`--refresh a,b`), never `--refresh a b`. It re-runs the
assets you name and every asset downstream of them in the task's cone (reason `refresh_cascade`),
so fresh data reaches the task. --no-cascade re-runs only the named assets; cached assets
downstream of them then do not reflect the refresh, and barca warns. A name that is not an
upstream asset is an error.
An upstream asset that is cached but whose artifact file is gone is computed again before the task
reads it (reason `artifact_missing`, a warning on stderr), so a deleted artifact does not fail the
run (barca docs cache).
The target must be a task; use `barca get` for assets. The target comes before the files:
`barca run pipeline.py deploy` exits 2 and prints `barca run deploy pipeline.py`. Every usage
error exits 2 and ends by pointing at `barca list` (with the files you gave, if any).
No files: barca reads every file in the project that imports barca (barca docs discovery).
Errors: in JSON mode stderr contains one JSON error object {error, code, kind, remediation}
(see barca docs agents). Exit 1 step failed, 2 usage error, 3 barca/infra failure, 130 cancelled.
A raising task, or one that calls sys.exit(), fails the run: exit 1, and the stdout JSON line has
status "failed" and failed_node. Stderr ends with the failed step, its first error line,
and the count of skipped downstream nodes.
More: barca docs tasks, barca docs cache, barca docs agents
