DOCS / CLI

Common options

Four options appear on more than one command. Each is declared once in the CLI, so a flag cannot mean two things depending on which command you reached it from.

The four

OPTION	SHORT	DEFAULT	MEANING
--bundle	-b	`databricks.yml`	Path to the Databricks Asset Bundle file.
--target	-t	required	The deployment target to act on. Must be declared in the bundle.
--output	-o	`table`	Output format: `table` or `json`, case-insensitive.
--profile	-p	resolution chain	Which stored credential to act as. Also read from `FINOWL_CONFIG_PROFILE`.

Which command takes which

COMMAND	-B	-T	-O	-P	OTHER
init	yes	required	—	yes	--prune
breakdown	yes	required	yes	yes	—
diff	yes	required	yes	yes	—
guard	yes	required	yes	yes	—
rename	yes	—	—	yes	NEW_NAME argument
auth login	—	—	—	yes	--no-browser, --org, --switch-account
auth logout	—	—	—	yes	—
auth describe	—	—	—	yes	—
auth token	—	—	—	yes	—
auth profiles	—	—	—	—	—

rename takes no target because a name belongs to the project, not to an environment. init takes no output format because it writes a file rather than rendering a result.

--bundle, -b

Defaults to databricks.yml in the working directory, which is where the Databricks CLI looks too. Point it elsewhere for a monorepo:

finowl breakdown -b products/sales/databricks.yml -t dev

finowl.yml is always read from the same directory as the bundle file, so moving the bundle moves both.

NOTE

A monorepo registers one project per bundle directory. One finowl.yml sits next to each databricks.yml, and each carries its own identity.

--target, -t

Required on every command that costs something, and checked against the bundle's targets: block before anything else runs.

finowl guard --target prod
finowl guard -t prod            # identical

In CI, drive it from the branch:

BUNDLE_TARGET: ${{ github.ref == 'refs/heads/main' && 'prod'
                || github.ref == 'refs/heads/staging' && 'staging'
                || 'dev' }}

# then
finowl guard --target "$BUNDLE_TARGET"

Why it is required rather than defaulted: The finowl CLI explains what the old guessing chain did. In short, a bundle priced for a target it never declared applies no overrides and no target variables, and reports the base bundle as an environment that does not exist.

--output, -o

table renders a Rich table for a human reading a terminal or a CI log. json prints one envelope on stdout for a machine.

finowl breakdown -t dev -o json | jq '.result.total_cost_incl_vat'
finowl guard -t prod -o JSON            # case-insensitive

The JSON envelope has the same shape for every command:

{
  "command": "guard",
  "version": "0.2.0",
  "timestamp": "2026-08-20T09:14:02Z",
  "bundle_path": "databricks.yml",
  "target": "prod",
  "passed": false,
  "result": { "cost": { ... }, "governance": { ... } }
}

A failure carries "passed": false and an "error" string instead of result.
Choosing json also suppresses the human-readable warnings, so stdout stays parseable.
json does not change exit codes. guard still exits 1 on a blocking violation.

IMPORTANT

--output text was renamed to --output table in 0.2.0. All three renderers produce tables; text never described what was printed.

--profile, -p

Names the stored credential to act as. Omit it and the resolution chain decides.

finowl breakdown -t prod --profile acme-eu

# or for a whole session
export FINOWL_CONFIG_PROFILE=acme-eu
finowl breakdown -t prod

On auth login and auth logout the flag means something subtly different: those commands operate on a profile rather than acting as one, so the value defaults to DEFAULT instead of falling through to the chain.

Boolean flags take no short form

--prune, --no-browser and --switch-account have no single-letter alias. A one-letter switch that changes what is written to a file is too easy to type by accident.

Reading help

Every option carries help text and shows its default. finowl COMMAND --help is the authoritative reference for the version you have installed.

$ finowl diff --help
Usage: finowl diff [OPTIONS]

  Show monthly cost diff between deployed state and planned bundle.

Options:
  -b, --bundle PATH        Path to the databricks.yml bundle file.
                           [default: databricks.yml]
  -t, --target TEXT        Target environment to act on. Must be declared in
                           the bundle's `targets:` block — it is never guessed.
                           [required]
  -o, --output [table|json]  Output format.  [default: table]
  -p, --profile TEXT       Authentication profile to act as (default: DEFAULT).
                           See `finowl auth profiles`.  [env: FINOWL_CONFIG_PROFILE]
  --help                   Show this message and exit.

PREVIOUS

Authentication

NEXT

finowl init