Configuration

Barca reads configuration from three layers. Precedence for every value:

CLI flag > environment variable > barca.toml > built-in default

For example, here are three equivalent ways to select the staging environment:

CLI flag

barca get pipeline.py --env staging

Environment variable

export BARCA_ENV=staging
barca get pipeline.py

barca.toml

barca.toml

default_env = "staging"

barca.toml

Discovered in the current working directory only (no walk-up): everything barca persists is cwd-anchored (.barca/), so the config governing that state is anchored the same way. Run barca from your project root.

# The environment used when --env / BARCA_ENV are not given.
default_env = "dev"

[remote]
# Root URI for shared remote state. Setting this enables remote mode:
# artifacts at {uri}/{env}/artifacts, shared metadata DB at
# {uri}/{env}/state/metadata.db.
uri = "abfss://cont@acct.dfs.core.windows.net/barca/my-project"

# Optional overrides, taken literally (no {env} templating):
# artifacts_uri = "abfss://.../custom-artifacts"
# state_uri = "abfss://.../custom/state.db"

# Metadata sharing:
#   "optimistic" — pull at run start, etag/generation-conditional push at run
#                  end, replay-on-conflict (default when a state uri resolves)
#   "off"        — artifacts remote, metadata local
state = "optimistic"

# Conflict retry budget for the conditional state upload.
push_retries = 5

# Forwarded verbatim to fsspec.filesystem(protocol, ...) — keyed by protocol.
[remote.storage_options.abfs]
account_name = "acct"

Unknown keys are hard errors (typo protection), as are malformed files.

Environment variables

Variable	Overrides	Notes
BARCA_ENV	default_env	Beaten by --env
BARCA_REMOTE_URI	[remote].uri
BARCA_ARTIFACT_URI	artifacts location	0.4.0 back-compat: literal, artifacts-only, bypasses env prefixing (warns when combined with a non-default env)
BARCA_STATE_URI	[remote].state_uri	Literal
BARCA_STATE	[remote].state	optimistic / off
BARCA_PUSH_RETRIES	[remote].push_retries
BARCA_STORAGE_OPTIONS	storage options	JSON keyed by protocol; merged over the toml tables per key

Environments (--env)

barca get/run/plan/serve/history/stats --env <name> separates all state per named environment, so dev/staging/prod never share cache or artifacts. Names match [A-Za-z0-9._-]+.

	env = default	named env <e>
local DB	.barca/metadata.db	.barca/envs/<e>/metadata.db
local artifacts	.barca/artifacts/	.barca/envs/<e>/artifacts/
remote artifacts	{uri}/default/artifacts/	{uri}/<e>/artifacts/
remote state	{uri}/default/state/metadata.db	{uri}/<e>/state/metadata.db

The default env keeps the pre-0.5.0 local layout, so existing projects need no migration.