DOCS / CLI

The finowl CLI

One binary, six commands. It reads your infrastructure-as-code, prices it, checks it against the rules in force, and reports the result. Everything except init and auth login is non-interactive and safe for CI.

Install

Python 3.9 or later. Four pure-Python dependencies and no compiled extensions, so it installs in seconds on a CI runner.

pip install finowl

$ finowl --version
finowl, version 0.2.0

Pin a version in anything that gates a deploy:

pip install finowl==0.2.0

Unpinned, a release changes your pipeline's behaviour without a commit of yours. See Run it in CI.

pipx install finowl works too, and is the better choice on a laptop where you want the command on PATH without touching a project environment. In CI, install it into the same environment the rest of the job uses.

What else needs to be installed

The Databricks CLI, on PATH, with workspace credentials configured the way you already configure them for databricks bundle deploy. Finowl shells out to it and inherits the environment — it sets no Databricks variables and never sees a workspace token.

COMMAND	RUNS	WHY
breakdown	`databricks bundle validate`	To catch `job_cluster_key` references that do not resolve. A cluster that is not there makes the cost wrong rather than missing.
diff	`databricks bundle plan`	To read the deployed state, which is one side of the diff.
guard	`databricks bundle plan`	Same, but only when a cost rule reaches the product. Governance-only policies need no workspace access at all.

Every supported Databricks authentication method, and which variables each one takes, is in Run it in CI.

Commands at a glance

COMMAND	DOES	INTERACTIVE
finowl init	Registers the project and writes `finowl.yml` — one workload word per compute, for one target.	Yes — refuses to run without a terminal
finowl breakdown	Prices every job, pipeline and warehouse in the bundle for one target.	No
finowl diff	Shows the monthly cost delta between the deployed state and the planned bundle.	No
finowl guard	Evaluates cost and governance rules. The CI gate.	No
finowl rename	Changes the project name on the platform and in the file, keeping history.	No
finowl auth	Sign in, sign out, inspect the active credential, list profiles.	`login` only

finowl [OPTIONS] COMMAND [ARGS]...

  init        Scaffold or update finowl.yml for one target
  breakdown   Calculate monthly cost breakdown for all workloads
  diff        Show monthly cost diff between deployed state and planned bundle
  guard       Check cost and governance guardrails against the bundle
  rename      Rename this project, keeping its history and budget
  auth        Sign in and inspect the active credential

Every costing command names its target

--target is required on init, breakdown, diff and guard, and the value must name a target your bundle declares. It is never guessed.

$ finowl breakdown --target prd
Target Error: databricks.yml: target 'prd' is not declared by this bundle.
Declared targets: dev, staging, prod.

Earlier versions defaulted to the target marked default: true, then to whichever appeared first in the file, then to the literal string dev. All three are gone. A guessed environment produces a confident number for something nobody asked about — a bundle priced as prd applies no target overrides and no target variables, and reports the base bundle as an environment that does not exist.

NOTE

The check happens against the bundle before the platform is contacted, so a typo costs one error and no network round trip.

CI runs and local runs

The CLI detects whether it is running inside a CI provider and files the run accordingly. You do not configure this.

In CI— identified by the pipeline id and commit SHA. Authoritative: it appears in run history, updates the deployment's cost figures and feeds the dashboards.
Locally — identified by your git identity and commit SHA, suffixed -dirty when the tree has uncommitted changes. A preview: it appears in a separate table and never overwrites deployment costs.

Run anything you like on your laptop. It cannot move the number the business is reading.

What happens without the platform

Every command that costs something needs the platform: pricing rates are fetched live, and guard fetches the rules. Without a credential the command exits 2 with one clear authentication error rather than a cascade of network failures.

Read next: Authentication for how credentials resolve, or Common options for the four flags every command shares.

PREVIOUS

5 — Learn

NEXT

Authentication