Single Go binary Dataform & dbt on BigQuery macOS · Linux · Windows MIT License

A unified interface for Dataform and dbt projects on BigQuery.

Browse a project's actions with their compiled SQL, columns and lineage, dry run and run them, edit source files with vim keys, and see what your branch changes: the actions it touches, the columns it drops or retypes that something downstream still reads, and what its queries would cost.

brew install --cask ashish10alex/tap/xf

Run xf web for the browser UI, xf for the TUI, or xf --nvim beside Neovim. All install options & prerequisites →

Workspace Preview

The same panes and keys in your browser or terminal

xf web opens the workspace in your browser on 127.0.0.1; xf opens the same panes in the terminal. Switch tabs below to inspect the workspace layout, branch column impact ledger, query cost check, and Neovim split.

1 actions · 11 total / filter · s scratch

● INCR xf_example.fct_orders
● TABLE xf_example.dim_customers
· VIEW xf_example.stg_orders
· VIEW xf_example.stg_payments
· ASSRT xf_example.assert_positive_order_totals

target · dev overrides .xf/config.json

schemaSuffix: ashish → xf_example_ashish

defer to prod: 2 upstream tables read from prod

3 run r run · d deps · D dependents · f full · a api

$ dataform run --actions xf_example_ashish.fct_orders

✓ dry run valid · scans 420.00 MiB ($0.003) · partitioned by order_date

2 sql · columns · lineage (tab / c) definitions/marts/fct_orders.sqlx · i incremental

-- Compiled incremental query (definitions/marts/fct_orders.sqlx)
DECLARE since DATE DEFAULT (
  SELECT MAX(order_date) FROM `alex-personal-dev-01.xf_example_ashish.fct_orders`
);

SELECT
  o.order_id,
  o.customer_id,
  o.order_date,
  o.status,
  SUM(p.amount) AS amount
FROM `alex-personal-dev-01.xf_example.stg_orders` AS o -- → prod
LEFT JOIN `alex-personal-dev-01.xf_example.stg_payments` AS p -- → prod
  USING (order_id)
WHERE o.order_date > since
GROUP BY 1, 2, 3, 4

4 log · jobs · history · preview · terminal (⌘j) 2/2 done · elapsed 4.1s · billed 420.00 MiB · est. $0.0026

✓ xf_example_ashish.fct_orders · 3.2s · slot 18.4s · 420.00 MiB · $0.0026

✓ xf_example_ashish.fct_orders_assertions_uniqueKey_0 · 0.9s · 0 B · $0.0000

NORMAL · h/j/k/l move · / search SQL · z zoom pane · ⌘↵ preview rows Engine: xf serve (cached compile · instant startup)

#	Model (`marts`)	Column changes vs BigQuery	Downstream readers (Dataplex Data Lineage, last 30d)
1	🚨 `orders`	dropped `discount` (NUMERIC) added `net_amount` (NUMERIC)	`finance.margins` · exact copy · still reads it (dry run fails) `reporting.revenue_report` · derived · no longer reads it (dry run passes)
2	⚠️ `dim_customers`	retyped `customer_id` (INT64 → STRING)	`marts.customer_segments_v2` · exact copy · unchanged on branch
3	✅ `daily` (view)	keeps every column	—

Dry-runs changed downstream readers in the branch to verify whether a dropped column is still referenced. CI flags: --fail-on critical|warning · --json

$ xf cost --fail-over 100GB
4 changed actions in feature/v2-marts vs origin/main @ 1125280 (working tree)

⚠ marts.fct_order_items  ≤ 4.20 TiB  $26.25  +4.20 TiB  (full refresh 9.00 TiB)  [MISSING PARTITION FILTER: event_date on raw.events]
✓ marts.dim_customers      1.80 GiB  $0.011  new
✓ staging.stg_pageviews  420.00 MiB  $0.003  no change
? ops.audit_log          not estimated: BigQuery gives no estimate for a script
────────────────────────────────────────────────────────────────────────────────
Total scanned: ≤ 4.20 TiB | Estimated cost: ≤ $26.26
✗ Gate failed: 4.20 TiB exceeds the limit of 100.00 GiB

Compares each changed action's bytes against the merge-base dry-run on today's tables, and flags missing partition filters. CI flags: --fail-over 100GB · --usd-per-tib 6.25 · --json

nvim · definitions/marts/dim_customers.sqlx LSP: xf · 1.80 GiB ($0.011)

config {
  type: "table",
  bigquery: { partitionBy: "first_order_date" }
}

SELECT
  c.customer_id,
  c.email,
  o.first_order_date,
  COALESCE(o.lifetime_value, 0) AS lifetime_value
FROM ${ref("stg_customers")} AS c
LEFT JOIN orders AS o USING (customer_id)

┌─ Hover (K on "stg_customers") ────────────────────┐
│ VIEW alex-personal-dev-01.xf_example.stg_customers│
│ customer_id   STRING   Primary key                │
│ email         STRING   Customer email address     │
│ country_code  STRING   ISO 2-letter country       │
└───────────────────────────────────────────────────┘

:Xf split · follows active buffer <C-w> switch window

● TABLE xf_example.dim_customers
  partitioned by first_order_date · clustered by customer_id
  assertions: uniqueKey, nonNull

── Lineage (O / tab) ───────────────────────────────
   upstream:   stg_customers, stg_orders, stg_payments
   downstream: reports.revenue_report

── Dry Run ─────────────────────────────────────────
  ✓ Valid SQL · scans 1.80 GiB ($0.011)
  Saving in Neovim recompiles once for both the split
  and LSP diagnostics.

Works out of the box with xf --nvim, or permanently via the nvim/ plugin directory and vim.lsp.enable("xf"). Attaches only inside Dataform and dbt projects.

Capabilities

Everything in one binary for local dev and CI

xf detects whether a directory is a Dataform project (workflow_settings.yaml or dataform.json) or a dbt project (dbt_project.yml) and shares a single background engine (xf serve) across interfaces.

1 · xf web & Terminal UI Browser + TUI

Browse actions, SQL, columns & lineage

Inspect every table, view, incremental model, assertion, test, seed, snapshot, declaration and source. Switch between compiled SQL, BigQuery schema columns, and upstream/downstream lineage with Tab or c.

xf web runs locally on 127.0.0.1 (or as a standalone Chrome/Edge --app window).
xf opens the same panes in the terminal (TUI is in maintenance mode; new features land in xf web).
Instant startup from cached compiles while a fresh compile runs in the background.

2 · Dry Run, Run & Defer to Prod BigQuery Execution

Run actions, tags, or only what changed

Every action is dry-run automatically as you browse and save. Press r to run an action (with dependencies d, dependents D, or full refresh f), T to run tags, or R to run only actions modified on your branch.

Defer to prod (xf web & xf run --defer): read unbuilt upstream tables from prod via proxy views in Dataform or --defer in dbt.
Dataform API runs (a) & xf watch: trigger or watch remote GCP workflows with live per-job slot time, bytes billed, and cost.

3 · Branch Impact & Cost Checks Local & Pull Requests

Catch broken downstream readers & costly scans

Compare your branch against origin/main before merging—interactively with I and C, from the CLI with xf impact and xf cost, or combined with xf check.

Column impact: queries Dataplex Data Lineage for downstream readers of dropped or retyped columns and dry-runs readers modified on the branch.
Query cost: estimates bytes scanned and on-demand USD delta vs merge-base, flagging missing partition filters.
CI integration: GitHub Action (ashish10alex/xf) and GitLab CI template post in-place PR comments and line notes.

4 · Source Editor, Scratch & Inspector xf web tools

Edit with vim keys, run scratch SQL & trace keys

xf web includes a full source editor (E), file tree (⌘b), Git source control (ctrl+g) with hunk staging and branch worktrees, and SQLFluff formatting.

Action preview (⌘↵) & Scratch queries (s or xf scratch): run ad-hoc BigQuery jobs with schema-aware completion, column filters, sorting, and CSV export.
Dependency inspector: trace a filter (e.g. order_id = 'A1') across a model and its upstream tables to spot where rows drop out.

5 · Neovim & Language Server xf --nvim · xf lsp

First-class Neovim split and LSP

Run xf --nvim to launch Neovim with xf in a side split and the language server enabled for the session—no Neovim configuration required—or add the nvim/ plugin permanently.

Go to definition (gd) on Dataform ref(), JS includes/, dbt ref(), source(), macros, and CTEs.
Hover cards (K) with BigQuery table columns, partitioning, and function signatures.
Live diagnostics from compile errors and BigQuery dry runs traced back to exact lines, plus query cost hints.

6 · Fast dbt & Multi-Project Workflow Dataform & dbt

Staged dbt compiles & project discovery

Large dbt projects on BigQuery don't block startup: xf runs dbt parse first to show the graph in about a second, then compiles the focused model ahead of the rest of the project.

Isolated artifacts: dbt compiles write to xf's cache directory, never overwriting your project's target/.
Project picker & search: run xf search ~/code to index all Dataform and dbt repos, and switch between them or open branches in git worktrees.
Agent skills: bundled skills in skills/xf-checks and skills/xf-run for Claude Code, Codex, and Antigravity.

Installation

Install `xf`

xf ships as a single executable with no runtime dependencies of its own. Later, run xf update (or xf --update) to update it the way it was installed.

macOS · Homebrew Recommended on Mac

Homebrew Cask

Installs the prebuilt macOS binary (Apple Silicon & Intel) and updates via xf update or brew upgrade --cask.

$ brew install --cask ashish10alex/tap/xf

macOS & Linux · Shell Script SHA-256 verified

curl install script

Downloads the latest release for your OS/arch, verifies it against checksums.txt, and installs to ~/.local/bin (or $XF_INSTALL_DIR).

$ curl -fsSL https://xf.dataformtools.com/install.sh | sh

Go Toolchain macOS · Linux · Windows

Build with `go install`

With Go 1.26+ (Go 1.21+ downloads the 1.26 toolchain automatically), installs into $GOBIN (default ~/go/bin).

$ go install github.com/ashish10alex/xf/cmd/xf@latest

Windows & Release Archives x64 & ARM64

winget, Scoop, PowerShell or GitHub Releases

Native builds for Windows 10 22H2 / 11, or download prebuilt archives for any platform from GitHub Releases ↗.

> winget install AshishAlex.xf

> irm https://raw.githubusercontent.com/ashish10alex/xf/main/scripts/install.ps1 | iex

Prerequisite 1 · Google Cloud ADC Required for BigQuery

Application Default Credentials

Dry runs, table hovers, scratch queries, and API runs call GCP as you through Application Default Credentials (separate from gcloud auth login). xf picks up a new login without a restart.

$ gcloud auth application-default login

Prerequisite 2 · Dataform CLI or dbt Project compiler

Dataform CLI or dbt (dbt-core / dbt v2)

For Dataform, install @dataform/cli (and run dataform init-creds if running via dataform run). For dbt, use dbt-core 1.x with dbt-bigquery (in .venv or on PATH) or dbt v2.

$ npm i -g @dataform/cli

$ pip install dbt-core dbt-bigquery

Quick Start

Up and running in a minute

Run xf web or xf from a project's root (the folder with workflow_settings.yaml, dataform.json, or dbt_project.yml)—or outside any project to pick or search for one.

Step 1 · Open a project Browser or terminal

Start `xf web` in your project

Opens the workspace in your browser. Outside a project, it lists the projects you have opened or lets you search a folder.

$ xf web

Prefer the terminal or Neovim?

$ xf --nvim

Step 2 · Try an example or discover repos Optional

Index local projects or open an example

Find every Dataform and dbt project under a directory so the project picker lists them:

$ xf search ~/code

Or try the example projects in a clone of the repo:

$ xf web --dir examples/dataform

Step 3 · Check a branch from the CLI Local & CI

Run column impact and query cost checks

Print a combined Markdown report comparing your branch against origin/main, or gate CI builds:

$ xf check --fail-on critical --fail-over 100GB

Check which settings and Google accounts are active:

$ xf config --auth

Essential Keys in xf web & the TUI Press ? anytime for every shortcut

⌘p / / Find file or action (# for actions)

Tab / c Cycle SQL, columns & lineage

r Run selected action

R Run what your branch changed

T Filter and run tags

I Branch column impact report

C Branch BigQuery cost estimate

E Edit source file beside SQL (xf web)

s New Scratch query from model (xf web)

⌘↵ Preview action rows in BigQuery (xf web)

B Switch branch or open in worktree

o Open file in connected editor

Documentation & Ecosystem

Guides, reference & companion tools

Read the documentation in the GitHub repository or explore the Dataform Tools VS Code extension.

xf web ↗

The browser UI, source editor, file tree, source control, Scratch queries, dependency inspector, and settings.

Checking a branch ↗

Column impact (xf impact), query cost (xf cost), xf check, GitHub Action, GitLab CI template, and agent skill.

Running & branches ↗

Run Changed, tag runs, switching branches, git worktrees, deferring to prod, and xf run --defer.

Neovim & LSP ↗

Using xf --nvim, installing the nvim/ plugin, and configuring the xf lsp language server.

dbt projects ↗

How xf parses and stages dbt-core 1.x and dbt v2 projects, targets, hooks, and differences from Dataform.

Settings & API runs ↗

Config files (.xf/config.json), running via the GCP Dataform API, watching workflows, and ADC accounts.

The TUI ↗

The terminal UI, action type filters ($table, $view), command palette, and project picker.

Windows guide ↗

Installing with winget, Scoop, or PowerShell, upgrading with xf stop, and Windows specifics.

Dataform Tools (VS Code) ↗

Using VS Code? Visit dataformtools.com for the Dataform Tools VS Code extension.