Run a long-running HTTP server exposing the orchestrator as a JSON API

Binds to 127.0.0.1 by default (local only); --host changes the address. There is no authentication. POST /run and /get trigger async runs; poll GET /status/<run_id> for results.

Usage: barca serve [OPTIONS] [FILES]...

Arguments:
  [FILES]...
          Python files or directories to read (default: every .py file under the project root that imports barca; see `barca docs discovery`). With --watch, files added later are not picked up until restart

Options:
  -p, --port <PORT>
          Port to bind on

          [default: 8274]

      --host <HOST>
          IP address to bind on; 0.0.0.0 (or ::) listens on every interface. The API has no authentication

          [default: 127.0.0.1]

      --watch
          Dev mode: re-parse the DAG when source files change

      --no-schedule
          Disable the cron scheduler (Schedule(...) assets will not auto-fire)

      --timezone <TIMEZONE>
          Timezone for cron evaluation: local (this machine's zone) or utc, in any letter case, or an IANA name such as America/New_York, which is case-sensitive. Any other value is a usage error

          [default: local]

      --read-only
          Inspect only: refuse runs, never schedule, read the metadata DB from snapshots

      --drain-timeout <SECONDS>
          Seconds to wait for runs in flight after SIGTERM or SIGINT before cancelling them (exit 1). Default: [server] drain_timeout in barca.toml, else 30. 0 cancels at once

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

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

Examples:
  BARCA_REMOTE=off barca serve pipeline.py   # local artifacts and history
  BARCA_LOG=json barca serve pipeline.py     # each line a JSON object on stdout, with run_id and node
  BARCA_TELEMETRY=datadog barca serve pipeline.py   # a trace per run; barca.serve.up via DogStatsD
  barca serve                                # every file in the project; files added later need a restart
  barca serve pipeline.py                    # HTTP API on 127.0.0.1:8274 plus the scheduler
  barca serve pipeline.py --port 8400        # custom port
  barca serve pipeline.py --host 0.0.0.0     # all interfaces (containers, VMs); the API has no auth
  barca serve pipeline.py --watch            # dev: re-parse the DAG when files change
  barca serve pipeline.py --no-schedule      # API only; Schedule(...) nodes do not fire
  barca serve pipeline.py --timezone utc     # evaluate cron in UTC (default: local)
  barca serve pipeline.py --timezone America/New_York   # an IANA zone name
  barca serve pipeline.py --read-only        # inspect only: no runs, no scheduler, DB never written
  barca serve pipeline.py --drain-timeout 120   # on SIGTERM, give runs in flight 2 minutes
  barca serve pipeline.py --env prod         # .barca/envs/prod/metadata.db, named on the startup line

Binds to 127.0.0.1 by default. There is no authentication: with --host 0.0.0.0, anyone who
can reach the port can trigger runs, so keep it on a private network or behind a proxy.
Invalid sources and their graph dependents are excluded; healthy definitions and schedules
continue. Startup logs, /health load_errors and the UI show unloaded files and affected nodes.
--watch restores repaired configured sources; one-shot commands remain strict.
From another machine, `--server <url>` on get, run, status, list, history and stats runs the
command on this server and prints it there as a local run would (barca docs server-mode).
`serve` itself always runs here: --server on it is a usage error.
The first line names the env, the artifact store and the metadata DB with its format:
[barca] env <env> (<source>); artifact store <store>; metadata <path> (db format <n>).
A writer sets an existing DB up before it binds: one it cannot use (empty, not SQLite,
a newer format, a malformed schema) or cannot open exits 3 naming the file and what to do.
A --read-only server keeps serving and reports it in /health metadata_error, and its routes
answer with an error whose reason is metadata_unusable. /health scheduler_enabled says
whether the scheduler is running.
With a store ([remote] uri), the metadata DB is backed up there every minute it changed
(barca docs remote); barca state restore refuses to run while the server is up.
SIGTERM or SIGINT drains: new runs get 503 with Retry-After, the scheduler stops, /health
says draining, and runs in flight finish (uploads included) for up to --drain-timeout seconds
(default 30, [server] drain_timeout in barca.toml). Exit 0 when they all finished. The deadline
or a second signal cancels the rest with reason "server shutdown": exit 1.
Lines go to stderr as text; BARCA_LOG=json writes them to stdout as JSON (barca docs telemetry).
More: barca docs scheduling
