QLineage CLI

Local SQL + dbt lineage for Snowflake and Redshift. No warehouse connection required.

QLineage CLI answers a simple question while you are working locally:

What feeds this SQL model, and how does the query get there?

It parses SQL locally with SQLGlot and can use dbt's target/manifest.json + compiled SQL when available. The package installs as qlineage-cli and the command is qlineage.

Install

Once published to PyPI:

uv tool install qlineage-cli

or:

pipx install qlineage-cli

For development / GitHub installs:

uv tool install git+https://github.com/MarkPhamm/qlineage_cli.git

Quick start

qlineage models/marts/fct_orders.sql --dialect snowflake

That parses the SQL and opens the workspace in your browser, backed by a local server on 127.0.0.1 so you can keep editing the query and press Visualize to rebuild the graph. Press Ctrl-C in the terminal to stop it.

Select any node to inspect its columns, types, joins, and SQL:

To print a tree in the terminal instead:

qlineage models/marts/fct_orders.sql --format tree

fct_customer_revenue
├── orders
│   └── ref:stg_orders
└── payments
    └── source:stripe.payments

Raw SQL works too:

qlineage query.sql --dialect redshift

dbt-aware mode

If a target/manifest.json exists in the project, QLineage CLI auto-discovers it.

When the SQL file matches a dbt model, it prefers the model's compiled SQL and maps physical relations back to friendly dbt names where possible.

dbt compile
qlineage models/marts/fct_customer_revenue.sql

To show the recursive dbt DAG instead of the internal SQL/CTE graph:

qlineage models/marts/fct_customer_revenue.sql --dbt-graph

or select a model directly:

qlineage --model fct_customer_revenue --dbt-graph

Column lineage

qlineage models/marts/fct_customer_revenue.sql --column revenue

Column lineage uses SQLGlot's lineage engine. It is strongest when dbt compiled SQL is available and columns are explicitly selected.

Export

JSON:

qlineage query.sql --format json

Mermaid:

qlineage query.sql --format mermaid

HTML is the default output. Piping or --no-open writes a self-contained static snapshot instead of starting the workspace server; the snapshot renders the same page but cannot re-analyze edited SQL. From inside the workspace you can also export the graph as SVG, PNG, or JSON.

qlineage query.sql
qlineage query.sql --no-open > lineage.html
qlineage query.sql --port 9000

Example:

flowchart TD
  fct_customer_revenue --> orders
  fct_customer_revenue --> payments
  orders --> stg_orders
  payments --> stripe_payments

Local workspace

Passing a SQL file opens the workspace with that query loaded. To start from a blank page instead:

qlineage ui
qlineage ui --port 8765 --dialect snowflake --no-open

Either way, parsing happens in Python on localhost; nothing is sent to a warehouse.

Query panel. Paste or import SQL with syntax highlighting and line numbers, pick a dialect, optionally name a column to trace, then choose Visualize. Editing the query and visualizing again rebuilds the graph in place.

The output node is named after the file or dbt model you opened, but only while the query still matches that file. Once you edit it, the name comes from the SQL itself: the target of a create table ... as or insert into, or final output for a plain SELECT.

Canvas. Drag nodes to rearrange them, drag the background to pan, and zoom with the controls or Cmd/Ctrl + scroll. Each node card shows its kind, name, column count, and either its join count or the key it is joined on downstream.

Inspector. Selecting a node shows parse status, its output columns with inferred types, an overview of upstream and downstream counts, join details, the exact columns consumed from each upstream relation, downstream consumers, and the SQL that produced that node.

Layout. Drag either panel edge to resize it, double-click an edge to reset it, or use the header tabs and the arrow buttons to hide a panel entirely. The theme toggle switches between dark and light.

Keyboard shortcuts

Command reference

qlineage [SQL_FILE] [options]
qlineage ui [options]

qlineage [SQL_FILE]

qlineage ui

Why local-first?

• no Snowflake credentials
• no Redshift credentials
• no SQL sent to a hosted service
• useful inside an editor, terminal, CI job, or PR workflow
• dbt metadata is already available locally after compile/build

Current scope

Supported

• Snowflake SQL
• Redshift SQL
• CTE/table-level lineage
• dbt ref() / source() fallback parsing
• dbt manifest.json auto-discovery
• compiled dbt SQL when available
• recursive dbt model/source lineage
• single-output-column lineage
• per-node output columns with types inferred from SQL expressions
• join detection and join keys per node
• terminal, JSON, Mermaid, and HTML output
• local browser workspace with resizable panes, a highlighted SQL editor, and a column inspector
• SVG, PNG, and JSON export from the workspace

Not yet

• schema-aware SELECT * expansion from a live warehouse
• macros that require executing arbitrary Jinja when no compiled SQL exists
• semantic layer / exposures / metrics

Those are good candidates for later releases.

Development

git clone https://github.com/MarkPhamm/qlineage_cli.git
cd qlineage_cli
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest
ruff check .

Try the included example:

qlineage examples/sql/customer_revenue.sql --dialect snowflake
qlineage examples/dbt/models/fct_customer_revenue.sql --dialect snowflake
qlineage ui --no-open

Release to PyPI

The repository includes a Trusted Publishing GitHub Actions workflow. After creating the qlineage-cli project on PyPI and configuring GitHub as a trusted publisher, publishing a GitHub Release will build and publish the package.

Screenshots in this README live in docs/ and are regenerated from examples/sql/customer_revenue.sql.

License

MIT