Barca runs Python asset graphs with caching by run hash.
Every asset output is fully materialized to an artifact file at step boundaries (json, pickle, parquet, or CSV) — that persistence is the cache checkpoint. pandas/polars DataFrames, pyarrow Tables and duckdb relations are written as parquet; parameter type annotations choose how downstream steps read it back (pandas by default, or polars, pyarrow, duckdb) but do not skip materialization. Start with `barca list` (run inside the project) to discover a project's assets and tasks; run `barca docs` for the manual.

Usage: barca <COMMAND>

Commands:
  get      Get assets — cache-aware, runs only the needed subgraph; prints their artifact paths
  run      Run a task and its dependency cone — the task always re-runs
  plan     Parse source files and emit the execution plan as JSON
  doctor   Diagnose project prerequisites without running pipeline steps
  logs     Read a run's recorded step output (stdout and stderr), without progress messages
  history  Show recent run history, or one run's steps and errors
  gc       Evict cached results to keep .barca/ under its size limit
  stats    Show execution statistics for an asset
  serve    Run a long-running HTTP server exposing the orchestrator as a JSON API
  queue    Show a barca server's run queue, or pause or resume it (experimental)
  list     List all discovered definitions (assets, tasks, sensors) with their deps
  status   Show every node's cache state, last materialization and artifact shape (read-only)
  sql      Query cached results with SQL (DuckDB) — each asset is a named view
  state    Metadata backups: list them, put one back in place of the local database, or start over
  docs     Show the built-in manual: concepts, output formats, examples, agent conventions
  version  Print version information
  help     Print this message or the help of the given subcommand(s)

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

  -V, --version
          Print version

Quick start:
  barca list                        # discover every asset, task and dependency in the project
  barca list pipeline.py            # ... or only those in one file
  barca get total pipeline.py       # run only what `total` needs (cached on re-run)
  barca run deploy pipeline.py      # run a task and its dependency cone
  barca docs                        # built-in manual: concepts, formats, examples

Output: results go to stdout as tables/summaries in a terminal and as JSON when piped or
captured; --json / --pretty (or BARCA_OUTPUT=json|pretty) override. Progress and errors go to
stderr. In JSON mode an error is one JSON line on stderr: {error, code, kind, remediation}.
Exit codes: 0 ok, 1 step failed, 2 usage error, 3 barca/infra failure, 130 cancelled.
Scripts and AI agents: barca docs skill (short, start here), barca docs agents (full contract)
