finowl init

finowl init [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]
      --prune         Remove orphan entries (computes no longer in the bundle)
                      instead of only warning about them.
  -p, --profile TEXT  Authentication profile to act as (default: DEFAULT).
                      [env: FINOWL_CONFIG_PROFILE]

What it does

1. Checks the target against the bundle, before asking a single question.
2. Resolves the project identity. A new bundle registers a project and receives an identifier. A bundle that already has one has it verified against the platform.
3. Detects every compute the bundle declares for that target: shared job clusters, inline task clusters, one serverless bucket per job, and each pipeline.
4. Asks one question per compute that has no word yet for this target.
5. Writes finowl.yml next to the bundle file.

It never re-asks a compute that already has a word. To change an estimate, edit the word in the file directly.

Registering the project

The first thing init asks is which project this bundle reports into. Two answers are valid.

Project identity
Paste the id from the project's page to report into an existing project,
or leave it blank to register a new one. Reports are filed under the id, so
the name stays a label you can change later with `finowl rename`.

     Project id (blank = new project):

• Blankregisters a new project. It asks for a name, defaulting to the bundle's own bundle.name.
• An id links this bundle to a project that already exists. Before linking, it names the project the reports would be filed under and its URL, so you can check the answer against what you were told.

A name already taken in your workspace is refused, and init offers to link to the project holding it instead. Two people independently typing analytics is an accident worth catching; a pasted identifier only ever arrives by deliberate copy-paste.

The workload questions

One word per compute, describing how much work runs on it per run. The prompt shows what it is asking about — the cluster shape, the number of workers, whether the resource runs continuously.

╭─ finowl init ──────────────────────────────────────────────────────╮
│                                                                    │
│  3 of 3 compute(s) in this bundle need a workload estimate.        │
│                                                                    │
│  Answer one word per compute — roughly how much work runs on it    │
│  per run:                                                          │
│                                                                    │
╰────────────────────────────────────────────────────────────────────╯

  word        typical run  example jobs
  trivial     ~5 min       health checks, notifications, tiny metadata refreshes
  light       ~20 min      incremental ingest of a few tables, small transforms
  medium      ~1 h         a typical daily batch ETL joining several sources
  heavy       ~3 h         large aggregations or feature engineering over 100s of GB
  intensive   ~8 h         historical backfills, big model training, TB-scale joins

For a job's serverless bucket the word also sets the assumed capacity.
Not sure? Pick the closest — you can edit finowl.yml anytime.

1/3  job daily_ingest · compute main
     shared cluster 'main': Standard_DS3_v2 × 4 workers
     Workload [trivial/light/medium/heavy/intensive]: light
     ✓ light

Serverless and continuous resources

• A job's serverless bucket collects every task with no declared compute. Its word sets the assumed serverless capacity as well as the duration.
• Continuous resources always run 730 hours a month, so the word does not set their duration. It still matters for serverless capacity, and the prompt says so.
• Warehouses are never asked about. They are natively sized and always priced at 730 hours.

Run it once per target

Words live under estimations.targets.<target> and are never inherited between environments. A bundle declaring three targets needs three runs.

finowl init --target dev
finowl init --target staging
finowl init --target prod

The word stands for how much data a compute chews through per run — exactly what differs between dev and prod. A prod job inheriting dev's light does not report uncertainty. It prints a cost, and passes or blocks a merge on it.

Orphans and --prune

When a compute disappears from the bundle — a renamed cluster, a deleted job — its entry in finowl.yml becomes an orphan. init warns about orphans and leaves them alone, because a rename must not break CI.

$ finowl init --target dev
Warning: targets.dev: job 'old_ingest' is not in the bundle
Warning: targets.dev: job 'daily_ingest' has no compute 'legacy' in the bundle

Remove them when you are ready:

$ finowl init --target dev --prune
Pruned 2 orphan entries.
finowl.yml already covers every compute in the bundle.
To change an existing estimate, edit the word in finowl.yml directly.

--prune checks every target section, not only the one named, so cleaning up after a rename takes one run.

It refuses to run in CI

finowl init is interactive-only and cannot run without a TTY.
Run it locally and commit the resulting finowl.yml — CI never prompts.

finowl.ymlis a committed file. A pipeline that could generate it would be answering the workload question on the developer's behalf, which is the one answer no machine has.

Common errors

The file it writes is documented in finowl.yml reference.