Command Line

Command

Purpose

konstruct build [path] [-u]

Build konstruct-out/ (graph.json, REPORT.md, graph.html and ontology.yml). -u/--update reuses cached analyses of anything unchanged (keyed by file hashes, compiled SQL, manifest checksums and the upstream columns each model sees). --no-dbt, --no-warehouse, --dialect, --out, --json (a machine-readable summary), --strict (exit 1 on warnings)

konstruct status

What Konstruct finds (configuration, dbt projects and whether their artefacts are current, warehouses, DAG, Dagster, PySpark, SQL, LookML and TMDL files, definitions files, vocabularies, Ossie models, and the inputs of each other repository listed in repositories), the ontology packs, loader lineage and usage the last build read, whether the project’s own connections are trusted, whether the graph is out of date and which inputs changed, where the skills are installed, and each installed plugin with whether the project enables it

konstruct trust [path]

Trust the project, after reviewing it: its own warehouse connections and paths outside it in konstruct.toml and profiles.yml are used, and dbt is run in it, until those settings change (see Trusting a Project’s Connections). Until then a build skips those connections, refuses those paths and never runs dbt. Prints the files covered, the environment variables they read and the dbt projects it runs dbt in. --revoke removes the record, --json

konstruct init

Write a commented konstruct.toml from what discovery found (--stdout to print it)

konstruct impact <table.column>

Everything downstream, drawn as a tree from the column (or, for a table, from the table through the tables it feeds): derived columns, relations, models that join, filter or group on it, tests, exposures, the DAG tasks that run them, and the business entities it touches. --depth N stops after N hops

konstruct trace <table.column>

Everything upstream, as a tree, each step marked direct (passed through or renamed) or transformed, and the business entities involved, its own included

konstruct path <a> <b>

Shortest connection between two tables or columns

konstruct search <words>

Find nodes by name or description, optionally --kind model; -m/--meaning also by meaning, through synonyms, abbreviations, formulas and lineage (see Searching by Meaning)

konstruct conflicts

Columns that compute the same business idea in different ways, with the sources, filters, joins and aggregations that differ and the file each is in, ranked by downstream reach. Writes CONFLICTS.md and conflicts.json. --format markdown, --fail-on-conflict, -n N (see Finding Conflicting Definitions)

konstruct check-sql <file>

Check SQL against the project’s definitions, keys and relationships, without running it: a measure that leaves out a filter its definition requires or computes it differently, a column of a retired term, a sum, count or average over a join that repeats its rows, mixed grains, joins off a relationship, and relations and columns the project does not have, each with its fix and evidence, and the corrected SQL where a fix changes nothing else (see Checking the SQL an Agent Writes). - reads standard input. Exit 1 when the query breaks an approved definition or a statement could not be analysed; --strict also on a warning. --format text|markdown|json (--json for short). With --history, checks the query history of the configured Snowflake, BigQuery and Databricks warehouses for shadow metrics instead (see Shadow Metrics): --days N, -n/--limit N distinct queries (default 5000), --pseudonymise, and --strict to exit 1 on a shadow metric of an approved term

konstruct define <term>

What a business term means: its definition, owner, status, grain, required filters and the columns that hold it. Takes a term, a synonym or a column (to list the terms that define it). Exit status 3 when no term matches

konstruct ontology

The entities, measures and relationships derived from the data stack, each with its confidence, with any broken rules (see The Ontology). --format yaml, --strict (exit 1 when a rule is broken)

konstruct entity <name>

One business entity: its key and the relations holding it, its properties, the relationships it takes part in and the metrics whose grain it is, each with its confidence and evidence (see Entities, Metrics and Relationships). Exit status 3 when no entity has that name

konstruct metric [name]

Every business metric, or those a name, a synonym or a column finds: the measures the ontology holds, those dbt’s semantic layer, Looker and Power BI define, and the metrics Konstruct proposes from the code, each with its definition, formula, grain, filters, owner, status and confidence. -n/--limit N. Exit status 3 when the name finds no metric

konstruct compile-metric <metric>

A metric by entities, properties and time grains, compiled to SQL without running it (see Compiling Metric Queries): --by PROP (an entity, entity.property, a property, or a grain such as month or order_date:month), --where EXPR, --since DATE, --until DATE, --time PROP and --dialect NAME, each --by and --where repeatable. It joins only along relationships the project shows many-to-one or one-to-one, onto keys shown unique, adds the metric’s required filters, and lists the facts it rests on with their confidence. --format text|sql|json (--json for short). Exit 1 when the query is refused, with the reason and the link whose join would repeat rows; 3 when the name finds no metric

konstruct relate <from> <to>

How two entities connect: one row that holds both, or the relationships on the way, with the cardinality, weakest confidence and check of the path and the SQL joins that follow it. Exit status 3 when no relationship connects them or either name is no entity

konstruct sensitivity [name]

Where sensitive data is, where the column lineage takes it and which transforms stop it: each sensitive column with what marks it (a business term’s sensitivity, a warehouse tag or a masking policy) or the marked columns it comes from, whether its model is marked to hold it, the exposures that show it, the reads a sanitiser or an aggregate over groups the SQL requires to hold at least k distinct keys stops (a hashed column stays sensitive, as pseudonymised), the columns that only join or filter, tables that copy a masked column in clear, and relations whose lineage is not known. With a table or column, only what concerns it, with the path for one column. --strict exits 1 when sensitive data reaches a built model or exposure not marked to hold it, or a table copies a masked column in clear (see Sensitive Data and Erasure)

konstruct erasure <key>

Where one person’s data ends up: from a key column, an entity (customer) or a table, every relation holding the person’s rows through copies, hashed copies, foreign keys, joins, copies of their personal data and the rows the person owns, with the columns holding the key, its sensitive columns and the action it needs (delete, rebuild, full refresh, or none for a view), and the exposures that show it. --levels N steps of owned rows (default 3)

konstruct explain <table.column>

How a column is calculated: its expression as SQL with CTEs and aliases inlined, the same formula composed down to source columns, and step by step each column on the way with the joins, filters and grouping that shape its rows (see Explaining a Column). --english also words the formula, its joins, filters and grouping, its grain and its terms in plain English (see In Plain English)

konstruct history <table.column>

When the column’s formula changed in git history, with each commit’s author, date and subject, and every change to the status, approval date, owner or definition of the business terms bound to it; says whether a term was approved after the latest formula change (see Reviewing Changes). -n/--limit N commits per file (default 50), --json

konstruct describe <name>

Columns, types, descriptions, tests and neighbours of one node; for a task, what it runs and its neighbours in the DAG

konstruct list [kind ...]

Every node of the given kinds (models, tables, sources, tasks, …; default all relations)

konstruct open

Open graph.html in a browser

konstruct serve [project]

Serve the viewer and the HTTP API from a local server on 127.0.0.1:8000. It builds first (--no-build serves the graph as it is), and open viewers reload whenever a build replaces graph.json, keeping their selection. --watch rebuilds when a file the last build read changes or is deleted, or a new file appears in dbt’s resource paths or an installed package’s macros; a file beside an input, in its folder with its extension, which the build did not read, is watched for appearing and for becoming an input, by the rule discovery found that input by, unless an exclude pattern discovery applied matches it (any other new file waits for the next build, and a moved project rebuilds at the next check), --open opens the browser, --port (0 for any free port; a port in use is an error), --host (another address needs a token, and a TLS proxy in front beyond a trusted network, see Access)

konstruct export <format>

The graph as OpenLineage events, Mermaid, Graphviz DOT or CSV, or the ontology as an Apache Ossie semantic model, OWL in Turtle, a Snowflake semantic view or Databricks metric views (see Exporting). -s NAME for the lineage of one table or column (not for the ontology formats), --columns to draw columns, --namespace for the OpenLineage namespace or the OWL ontology’s IRI, -o FILE. A plugin the project enables can add formats

konstruct diff [--base REF]

What the working tree (or --head REF) changes compared with the base (default: the merge base with main). Either can be a date, such as --base 2026-10-01 or --base "2026-10-01 14:30", for the last commit on the current branch before it (a date alone means its start, in local time): columns added, removed or changed with their expressions before and after, changed join and filter conditions, breaking changes, DAG changes, dbt tests, sources and exposures added or removed in YAML, the downstream impact of each, and a column-aware dbt build --select that rebuilds only what the change affects. --format markdown for a pull request comment, --json (as --format json), --fail-on-breaking for CI

konstruct gate [--base REF]

The check a change must pass before it is proposed: brings the graph up to date with the working tree and fails (exit 1) on a removed column something still reads, an approved term whose meaning changes (in definitions.yml, or through a column it names or one upstream of it), a changed column that computes a business idea differently from an existing one, a data law recorded in laws.json that held on all the data and no longer follows from the SQL, a changed column that a repository in repositories pins in its konstruct.lock, or sensitive data the change moves into a model or exposure not marked to hold it, a masked column it copies in clear or a sensitivity mark it takes away, each with how to fix it, and says where the data laws it judged against came from, and on the findings of the checks plugins add (see The Gate). --no-update uses the graph as it is, --no-dbt and --no-warehouse apply to the update, --format text|markdown|json (--json for short), --json-file

konstruct release-notes

The changes to formulas, filters and business terms in a range of commits: each changed column and relation with its formula or conditions before and after in SQL and plain English, the commit, what it affects downstream, and whether its business terms were approved after it (see Release Notes). --since REF (a commit, tag or date; default the latest tag), --until REF, -n/--limit N, --format text|markdown|json, --json

konstruct timeline

How the business’s meaning changed, commit by commit: the entities, relationships, properties and metrics each commit added, removed, renamed or changed, a metric’s composed formula, the rows it is computed over and its required filters, trust, and each definition’s status, owner and approval date, with the commit’s author, co-authors and date, in plain English, and a release note for each metric change (see Timeline). Each commit’s world is built from its own files, without running dbt or connecting to a warehouse, and kept in the user’s cache. --since REF (a commit, tag or date; default the whole history), --until REF, --file PATH (repeatable), -n/--limit N (default 50), --format text|markdown|json, --json

konstruct verify

Test the column lineage against the data by perturbation, in a DuckDB file, a Postgres database, or a sample of Snowflake, BigQuery, Databricks or Trino (--warehouse snowflake); writes VERIFY.md and verify.json and marks confirmed edges in the graph. On DuckDB and Postgres it also checks the ontology’s keys and relationships over whole tables (see Keys and Relationships); --no-ontology leaves that out. --seed, --rows, --model, --strict. With --mutate, mutation tests each dbt model’s data and unit tests instead and writes MUTATION.md and mutation.json (see Mutation Testing): --max-mutants N, --operators LIST, --no-suggest, --markdown FILE. With --why COLUMN --where col=value, lists the source rows behind one value instead, each with its share, and the related rows a filter or join left out, with sensitive values and the shares of a value computed from one masked (see The Rows Behind a Value): -n/--limit N, --json. With --effect, runs each changed model as it was before and after each commit since --since REF (default: the latest tag) until --until REF on the same data and prints the release notes with the difference (see The Effect on Today’s Data): --format text|markdown|json. With --laws, proposes the conservation, count and additivity laws each model’s SQL implies and checks them against the data, writing laws.json, which the gate reads (see Data Laws): --propose only proposes them, reading no warehouse and writing nothing, --tolerance X, --rows N for the additivity probes, --strict (exit 1 on a broken law)

konstruct lock [name ...]

Pin what each upstream column the project reads means in konstruct.lock: its formula composed down to source columns, the row conditions on the way, its sources, its type and its business terms (see Pinning What You Read). Names limit it to those columns, relations, exposures or terms. A pinned column keeps its pin until --update accepts every change, or --update COLUMN ... the changes to those. --check compares the lockfile with the build instead and exits 1 when a pinned column changed, showing each change, who made it and the commands to accept it or keep the locked meaning; --no-history reads no git history, --format markdown suits a pull request comment. --no-write, --json

konstruct query "<question>"

Free-text question: ranks nodes by its words and returns them with their connections, plus impact or lineage when the question asks for it. There is no language model in Konstruct; the agent reads the result

konstruct install

Install the Konstruct skills and instructions for coding agents: --agent claude|cursor|codex|copilot|gemini|windsurf (one or more; both, the default, or all), --target DIR for a repository rather than the home directory, --mcp to register the MCP server in each agent’s configuration, --force to replace files and sections edited by hand (see Coding Agents)

konstruct hook post-edit

For a Claude Code PostToolUse hook: reads the hook event on standard input and, when the edited file is SQL, dbt YAML, a definitions file or an Ossie model in a repository with a Konstruct graph, runs the gate on a copy of the graph built from files alone (no dbt, no warehouse) and prints the result as hook JSON. --remind only reminds the agent to run the gate

konstruct receipts issue <name> ...

Record what an answer rests on: for each column it names (directly, or through a relation, an exposure or a business term), its formula composed down to source columns, the conditions on its rows, its sources, type, bound terms and verification state, and the build it answered from; prints a citation to put under the answer. --question TEXT, --answer TEXT, --json. konstruct receipts show ID prints one receipt, without needing a graph; konstruct receipts check [ID ...] says whether what each rests on still holds, after bringing a graph older than its inputs up to date (--no-refresh to leave it, when such receipts are unchecked), and exits 1 when one is stale, unchecked, tampered or unreadable, --no-history (see Answer Receipts)

konstruct mcp

Run the MCP server on stdio. --no-prompts offers the tools and resources without the workflow prompts

konstruct plugins

Every installed plugin, by distribution: its inputs, export formats, gate checks, ontology packs and MCP tools, the plugin API version each targets, and whether each runs for the project and why; then Konstruct’s own components. --json (see Writing a Plugin)

Tables and columns can be named as orders, main.orders, orders.amount, jaffle_shop.main.orders.amount, ecom.raw_orders for a dbt source, dag_id.task_id for a task, or by dbt unique id. When nothing matches, Konstruct suggests the three closest names, by the words they share or, for a misspelling, by spelling, with a search to try; when a name is ambiguous, it lists the candidates.

Every command takes -C DIR (before or after the command name) to work on another directory, --no-plugins to run no plugin whatever konstruct.toml enables, and --trust-config to trust the project for that command, as KONSTRUCT_TRUST_CONFIG=1 does; query commands also find konstruct-out in any parent directory. Query commands build the graph if there is none, warn when inputs changed since the last build, and take --refresh to update it first, --json for structured output and --graph FILE to read a specific graph. Exit status is 0 on success, 1 on an error (and when gate, check-sql or lock --check fails, or compile-metric refuses a query), 2 on a usage error and 3 when path or relate finds no connection, or define, entity, metric, relate or compile-metric finds nothing by that name. konstruct --help lists the commands by what they are for, and konstruct <command> --help ends with examples.

Output

Every result starts with a line naming what it is about and a one-line summary, then sections of aligned tables; impact and trace draw a tree whose edges say how each value is derived.

Where the output goes

What it looks like

A terminal

Box-drawing connectors and colour: bold headings, the subject in cyan, green, yellow and red for state, faint text for what is secondary, and SQL keywords and literals picked out. Only the sixteen standard ANSI colours are used, so the terminal’s theme keeps them readable on a light or dark background. Tables fit the window: less important columns are left out first, then long values are cut with an ellipsis; summaries and formulas wrap

A pipe or a file, or TERM=dumb

Plain ASCII text with no escape codes, no truncation and no wrapping, one record per line, so it is stable for grep, diffs and coding agents. It is the same text as str(result) in Python

--json

The result’s data, unchanged by where it goes

NO_COLOR or --no-color turns colour off and keeps the layout; FORCE_COLOR turns it on in a pipe. While a build, an update, verify, diff or gate runs, a spinner on stderr shows the stage and how many models have been analysed; it appears only on a terminal, never in CI (where CI is set) or with -q, and -v prints the stages as lines instead. Progress, warnings and errors go to stderr, so stdout holds only the result. An error says what went wrong on its first line, then why, the names it may have meant, and a command to try.

Every Command and Option

Generated from the command’s own argument definitions.

Derive an ontology and column-level lineage from a data stack (dbt, SQL, Airflow, Dagster, Looker, Power BI and the warehouse), check them against the data, and check each change, for people and coding agents.

Usage: konstruct [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--version]
                 <command> ...

Named Arguments

-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--version

show program’s version number and exit

commands

<command>

Possible choices: build, trust, status, init, impact, trace, path, search, describe, conflicts, check-sql, define, ontology, entity, metric, relate, compile-metric, sensitivity, erasure, explain, history, list, query, export, diff, release-notes, timeline, gate, verify, lock, open, install, hook, serve, receipts, mcp, plugins

Sub-commands

build

Build konstruct-out/graph.json, REPORT.md, graph.html and ontology.yml.

konstruct build [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [-u]
                [--out DIR] [--no-dbt] [--no-warehouse] [--dialect DIALECT] [--strict] [--json]
                [path]
Positional Arguments
path

project directory (default: -C or the current directory)

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

-u, --update

reuse cached analyses of unchanged inputs

Default: False

--out

output directory (default: <project>/konstruct-out)

--no-dbt

never run dbt; use the artefacts in target/

Default: False

--no-warehouse

do not connect to any warehouse

Default: False

--dialect

SQL dialect for sqlglot (default: from the dbt adapter or warehouse)

--strict

exit with status 1 if there are warnings

Default: False

--json

print a JSON summary instead of text

Default: False

Examples:

konstruct build                    build the graph for the current directory
konstruct build -u                 reuse the analyses of unchanged inputs
konstruct build --no-dbt --strict  never run dbt, and fail on any warning

trust

After review, use the project’s own connections and run its dbt.

konstruct trust [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--revoke]
                [--json]
                [path]
Positional Arguments
path

project directory (default: -C or the current directory)

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--revoke

stop trusting it

Default: False

--json

print JSON instead of text

Default: False

Examples:

konstruct trust                 after reviewing the project: use its connections, run its dbt
konstruct trust --revoke        stop trusting it
konstruct build --trust-config  trust it for one command, in CI on a reviewed branch

status

Show what Konstruct finds here and whether the graph is up to date.

konstruct status [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--json]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

Examples:

konstruct status         what Konstruct finds here, and whether the graph is current
konstruct status --json  the same as JSON

init

Write a konstruct.toml that records what discovery found.

konstruct init [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--force]
               [--stdout]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--force

replace an existing konstruct.toml

Default: False

--stdout

print the configuration instead of writing it

Default: False

Examples:

konstruct init           write konstruct.toml from what discovery finds
konstruct init --stdout  print it instead

impact

Everything downstream of a table, model or column.

konstruct impact [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--depth N]
                 [--json] [--graph FILE] [--refresh] [--no-build]
                 NAME
Positional Arguments
NAME

e.g. orders, main.orders or orders.amount

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--depth

stop after N hops

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct impact orders.amount         what breaks if orders.amount changes
konstruct impact stg_orders --depth 2  two hops downstream of a model
konstruct impact orders.amount --json  the same as JSON, for scripts

trace

Everything upstream of a table, model or column.

konstruct trace [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--depth N]
                [--json] [--graph FILE] [--refresh] [--no-build]
                NAME
Positional Arguments
NAME

e.g. orders, main.orders or orders.amount

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--depth

stop after N hops

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct trace customers.lifetime_value  the source columns a value comes from
konstruct trace orders --depth 1          the direct inputs of a model

path

The shortest connection between two tables or columns.

konstruct path [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--json]
               [--graph FILE] [--refresh] [--no-build]
               FROM TO
Positional Arguments
FROM
TO
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct path raw_payments customer_dashboard  how a seed reaches a dashboard

describe

Columns, types, descriptions, tests and neighbours of one node.

konstruct describe [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--json]
                   [--graph FILE] [--refresh] [--no-build]
                   NAME
Positional Arguments
NAME
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct describe orders              columns, tests and neighbours of a model
konstruct describe orders.amount       one column, with its formula
konstruct describe my_dag.load_orders  a DAG task

conflicts

Columns that compute the same business idea in different ways.

konstruct conflicts [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [-n N]
                    [--format FORMAT] [--no-write] [--fail-on-conflict] [--json] [--graph FILE]
                    [--refresh] [--no-build]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

-n, --limit

at most N conflicts

--format

Possible choices: text, markdown

text or markdown

Default: 'text'

--no-write

do not write CONFLICTS.md and conflicts.json

Default: False

--fail-on-conflict

exit with status 1 if any conflict is found

Default: False

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct conflicts                               columns that compute one idea in different ways
konstruct conflicts --format markdown --no-write  as markdown, writing nothing
konstruct conflicts --fail-on-conflict            exit 1 on a conflict, for CI

check-sql

Check SQL against the project’s definitions, keys and relationships, without running it.

konstruct check-sql [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                    [--format FORMAT] [--strict] [--history] [--days N] [-n N] [--pseudonymise]
                    [--json] [--graph FILE] [--refresh] [--no-build]
                    [FILE]
Positional Arguments
FILE

a file of SQL, or - to read it from standard input

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--format

Possible choices: text, markdown, json

text, markdown or json

Default: 'text'

--strict

exit with status 1 on a warning as well as an error; with –history, on a shadow metric of an approved term

Default: False

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

query history

with –history: the queries run in the project’s warehouses, checked

--history

check the query history of the configured Snowflake, BigQuery and Databricks warehouses for measures computed differently from their definitions (shadow metrics)

Default: False

--days

read N days of history (default: [usage] days, 90)

-n, --limit

the most distinct query texts read, those run most often first (default 5000)

Default: 5000

--pseudonymise

count people without naming them, and leave literals out of the example queries

Default: False

Examples:

konstruct check-sql query.sql               check a query against the definitions before it runs
konstruct check-sql - --strict < query.sql  from standard input; exit 1 on a warning too
konstruct check-sql --history --days 30     shadow metrics in the warehouse query history

define

What a business term means, who owns it and which columns hold it.

konstruct define [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--json]
                 [--graph FILE] [--refresh] [--no-build]
                 TERM [TERM ...]
Positional Arguments
TERM

a term, a synonym, or a column such as orders.amount

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct define lifetime value  a term, by name or synonym
konstruct define orders.amount   the terms bound to a column

ontology

The entities, measures and relationships derived from the data stack.

konstruct ontology [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                   [--format FORMAT] [--strict] [--json] [--graph FILE] [--refresh] [--no-build]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--format

Possible choices: text, yaml

text or yaml

Default: 'text'

--strict

exit with status 1 if any ontology rule is broken

Default: False

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct ontology                entities, measures and relationships
konstruct ontology --format yaml  the ontology.yml the build writes
konstruct ontology --strict       exit 1 on a rule violation

entity

One business entity: its key, properties, relationships and metrics.

konstruct entity [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--json]
                 [--graph FILE] [--refresh] [--no-build]
                 NAME [NAME ...]
Positional Arguments
NAME

an entity, or the term naming it

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct entity customer         its key, properties, relationships and metrics
konstruct entity customer --json  the same as JSON, for an agent

metric

Business metrics, defined and proposed, with formula, grain and confidence.

konstruct metric [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [-n N]
                 [--json] [--graph FILE] [--refresh] [--no-build]
                 [NAME ...]
Positional Arguments
NAME

a metric or a column holding one; all of them if left out

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

-n, --limit

at most N metrics

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct metric                 every metric, defined and proposed
konstruct metric lifetime value  one metric: definition, formula, grain and trust
konstruct metric orders.amount   the metric a column holds

relate

How two entities connect: relationships, cardinality and joins.

konstruct relate [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--json]
                 [--graph FILE] [--refresh] [--no-build]
                 FROM TO
Positional Arguments
FROM

an entity, such as customer

TO

another entity, such as payment

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct relate customer payment       the relationships between them and the joins
konstruct relate order customer --json  the same as JSON

compile-metric

A metric by entities and properties, compiled to SQL that joins safely, unrun.

konstruct compile-metric [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                         [--by PROP] [--where EXPR] [--since DATE] [--until DATE] [--time PROP]
                         [--dialect NAME] [--format FORMAT] [--json] [--graph FILE] [--refresh]
                         [--no-build]
                         METRIC [METRIC ...]
Positional Arguments
METRIC

a metric, as konstruct metric finds it

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--by

group by an entity (its key), a property (customer.first_name) or a time grain (month, order_date:month); repeatable

--where

a condition on properties, as SQL (“customer.first_name = ‘Ann’”); repeatable

--since

the first date covered (YYYY-MM-DD)

--until

the date after the last one covered

--time

the property that dates the metric (default: its relation’s one date)

--dialect

the SQL dialect to write (default: the project’s)

--format

Possible choices: text, sql, json

text, sql or json

Default: 'text'

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct compile-metric lifetime value --by customer                                    the SQL of a metric by an entity
konstruct compile-metric order amount --by customer.first_name --by month                by a property and a month
konstruct compile-metric order amount --where "status = 'completed'" --since 2024-01-01  on some rows, from a date
konstruct compile-metric order amount --format sql --dialect snowflake                   only the SQL

sensitivity

Where sensitive data is, where the lineage takes it and which transforms stop it.

konstruct sensitivity [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                      [--strict] [--json] [--graph FILE] [--refresh] [--no-build]
                      [NAME]
Positional Arguments
NAME

only this table, model or column

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--strict

exit with status 1 if sensitive data reaches a model or exposure not marked to hold it, or a table copies a masked column in clear

Default: False

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct sensitivity                  sensitive columns, where the lineage takes them and what stops it
konstruct sensitivity customers.email  why one column is sensitive, or what stopped it
konstruct sensitivity --strict         exit 1 when sensitive data reaches a model not marked to hold it

erasure

Every relation that holds one person’s rows, found by a key, for an erasure request.

konstruct erasure [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--levels N]
                  [--json] [--graph FILE] [--refresh] [--no-build]
                  KEY
Positional Arguments
KEY

a key column (customers.customer_id), an entity (customer) or a table

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--levels

how many steps of rows the person owns to follow, such as an order’s payments (default 3)

Default: 3

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct erasure customer                      every relation holding one customer's rows, and what to do with each
konstruct erasure customers.customer_id --json  the same from a key column, as JSON

explain

A column’s formula, composed down to its source columns.

konstruct explain [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--english]
                  [--json] [--graph FILE] [--refresh] [--no-build]
                  COLUMN
Positional Arguments
COLUMN

e.g. orders.amount

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--english

also word the formula, its joins, filters and grouping, and its terms in plain English

Default: False

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct explain customers.lifetime_value             its formula, down to source columns
konstruct explain orders.credit_card_amount --english  the same formula in plain English

history

When a column’s formula changed, and who approved the terms bound to it.

konstruct history [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [-n N]
                  [--json] [--graph FILE] [--refresh] [--no-build]
                  COLUMN
Positional Arguments
COLUMN

e.g. customers.lifetime_value

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

-n, --limit

the most commits to read per file (default 50)

Default: 50

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct history customers.lifetime_value  formula changes and approvals
konstruct history orders.amount -n 200      read further back

list

List nodes by kind (default: tables, models, sources, seeds and snapshots).

konstruct list [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--json]
               [--graph FILE] [--refresh] [--no-build]
               [KIND ...]
Positional Arguments
KIND

any of source, table, column, model, seed, snapshot, dag, task, test, exposure (plurals work)

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct list             tables, models, sources, seeds and snapshots
konstruct list tasks dags  the orchestration

query

Answer a free-text question from the graph.

konstruct query [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--depth N]
                [--json] [--graph FILE] [--refresh] [--no-build]
                QUESTION [QUESTION ...]
Positional Arguments
QUESTION
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--depth

neighbourhood depth around matches

Default: 1

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct query what breaks if I change payment_method  impact, from a question
konstruct query where does lifetime value come from     lineage, from a question

export

The graph as OpenLineage, Mermaid, Graphviz DOT or CSV, or the ontology as Apache Ossie, OWL, a Snowflake semantic view or Databricks metric views.

konstruct export [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [-o FILE]
                 [-s NAME] [--columns] [--namespace NS] [--json] [--graph FILE] [--refresh]
                 [--no-build]
                 FORMAT
Positional Arguments
FORMAT

Possible choices: openlineage, mermaid, dot, csv, ossie, owl, semantic-view, metric-view

openlineage, mermaid, dot, csv, ossie, owl, semantic-view, metric-view, or a format a plugin adds

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

-o, --output

write to FILE instead of stdout

-s, --select

only the lineage of this table or column, both directions (not for the ontology formats)

--columns

mermaid and dot: draw columns and column lineage

Default: False

--namespace

openlineage: dataset namespace (default: <dialect>://konstruct); owl: the ontology IRI

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct export mermaid -s orders --columns         a Mermaid diagram of one model
konstruct export openlineage -o lineage.json         OpenLineage events for a catalogue
konstruct export ossie -o model.yml                  the ontology as an Apache Ossie model
konstruct export semantic-view -o semantic_view.sql  the ontology as a Snowflake semantic view

diff

What a change does, column by column, compared with a base commit (git).

konstruct diff [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--base REF]
               [--head REF] [--format FORMAT] [--json] [--json-file FILE] [--fail-on-breaking]
               [--graph FILE] [--refresh] [--no-build]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--base

commit or date (2026-10-01) to compare with (default: the merge base with main)

--head

commit or date to compare (default: the working tree)

--format

Possible choices: text, markdown, json, selector

text, markdown, json or selector: markdown suits a pull request comment, and selector prints only the dbt selection

Default: 'text'

--json

print JSON instead of text

Default: False

--json-file

also write the result as JSON to FILE (for CI)

--fail-on-breaking

exit with status 1 on a breaking change

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct diff                                          this branch against its merge base with main
konstruct diff --base origin/main --format markdown     for a pull request comment
dbt build --select $(konstruct diff --format selector)  build only what the change needs

release-notes

The changes to formulas, filters and business terms in a range of commits (git).

konstruct release-notes [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                        [--since REF] [--until REF] [-n N] [--format FORMAT] [--json]
                        [--graph FILE] [--refresh] [--no-build]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--since

commit, tag or date (2026-10-01) the notes start after (default: the latest tag)

--until

commit, tag or date the notes end at (default HEAD)

-n, --limit

the most commits read (default 200)

Default: 200

--format

Possible choices: text, markdown, json

text, markdown or json: markdown suits a wiki page or a chat message

Default: 'text'

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct release-notes                                       what changed in each formula since the latest tag, in plain English
konstruct release-notes --since 2026-10-01 --format markdown  to post to a wiki or a channel

timeline

How the business’s meaning changed, commit by commit (git).

konstruct timeline [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                   [--since REF] [--until REF] [--file PATH] [-n N] [--format FORMAT] [--json]
                   [--graph FILE] [--refresh] [--no-build]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--since

commit, tag or date (2026-10-01) the timeline starts after (default: the first)

--until

commit, tag or date the timeline ends at (default HEAD)

--file

only the commits that changed this file or directory, relative to the project (repeatable)

-n, --limit

the most commits read, the most recent (default 50)

Default: 50

--format

Possible choices: text, markdown, json

text, markdown or json: markdown suits a wiki page or a chat message

Default: 'text'

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct timeline                                 how the business's meaning changed, commit by commit, in plain English
konstruct timeline --since v1.4 --format markdown  the changes since a release, to post
konstruct timeline --file models/marts             only the commits that changed the marts

gate

The check a change must pass before it is proposed (exits 1 when it fails).

konstruct gate [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--base REF]
               [--format FORMAT] [--json] [--json-file FILE] [--graph FILE] [--no-update]
               [--no-dbt] [--no-warehouse]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--base

commit or date to compare with (default: the merge base with main)

--format

Possible choices: text, markdown, json

text, markdown or json

Default: 'text'

--json

print JSON instead of text

Default: False

--json-file

also write the result as JSON to FILE (for CI)

--graph

use this graph.json instead of finding konstruct-out

--no-update

use the graph as it is (just built, say)

Default: False

--no-dbt

never run dbt when updating the graph

Default: False

--no-warehouse

connect to no warehouse when updating the graph

Default: False

Examples:

konstruct gate                                           the check to pass before opening a pull request
konstruct gate --base origin/main --json-file gate.json  in CI, keeping the result

verify

Test the column lineage against the data by perturbing inputs (DuckDB, Postgres, or a sample of Snowflake, BigQuery, Databricks or Trino).

konstruct verify [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [-m NAME]
                 [--seed SEED] [--rows N] [--warehouse WAREHOUSE] [--strict] [--no-ontology]
                 [--mutate] [--max-mutants N] [--operators LIST] [--no-suggest] [--markdown FILE]
                 [--why COLUMN] [--where COLUMN=VALUE] [-n N] [--effect] [--timeline] [--since REF]
                 [--until REF] [--format FORMAT] [--laws] [--propose] [--tolerance X] [--json]
                 [--graph FILE] [--refresh] [--no-build]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

-m, --model

only this model (repeatable)

--seed

random seed, for reproducible runs (default 1729)

Default: 1729

--rows

rows copied per input (default 10000, 1000 with –mutate, 1000000 with –why or –effect)

Default: 10000

--warehouse

DuckDB file, postgresql:// URL, or snowflake, bigquery, databricks or trino for the configured one, sampled (default: discovered)

--strict

exit with status 1 if any influence is unexplained

Default: False

--no-ontology

do not check the ontology’s keys and relationships over whole tables

Default: False

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

mutation testing

with –mutate: would the dbt tests fail if a model were wrong?

--mutate

run small changes to each dbt model against its data and unit tests, and suggest a test for each change they miss; writes MUTATION.md and mutation.json

Default: False

--max-mutants

the most mutants run per model (default 30)

Default: 30

--operators

comma-separated kinds of mutation (default all): aggregate, filter, join_condition, join_type, boundary, comparison, date, coalesce, case

--no-suggest

do not look for a test that kills each survivor

Default: False

--markdown

also write the report as markdown to FILE

the rows behind a value

with –why: which source rows make up one value, and which were left out

--why

list the source rows behind one value of COLUMN (e.g. customer_ltv.lifetime_value), each with its share, and the related rows a filter or join left out

--where

the row of the model whose value to explain, by an output column (repeatable)

-n, --limit

the most rows listed in each table (default 50)

Default: 50

the effect of a change

with –effect: what each formula change does on today’s data

--effect

run each changed model as it was before and after each commit on the same data, and print the release notes with the difference

Default: False

--timeline

with –effect: read the changes as the timeline does, metric by metric, and print the timeline

Default: False

--since

commit, tag or date the changes start after (default: the latest tag)

--until

commit, tag or date the changes end at (default HEAD)

--format

Possible choices: text, markdown, json

with –effect: text, markdown or json

Default: 'text'

data laws

with –laws: the totals the lineage says the data must keep, checked per day

--laws

propose the conservation, count and additivity laws each model’s SQL implies and check them against the data; writes laws.json, which the gate reads

Default: False

--propose

with –laws, only propose them, reading no warehouse and writing nothing

Default: False

--tolerance

how far a floating-point total may part from its source’s, relative to the day’s sum of magnitudes (default 1e-9); integer and decimal totals must agree exactly

Examples:

konstruct verify                                                          check every model in the discovered warehouse
konstruct verify -m orders --strict                                       one model; exit 1 on an unexplained influence
konstruct verify --warehouse snowflake --rows 2000                        a sample of the configured Snowflake
konstruct verify --mutate -m orders                                       would orders' dbt tests catch a wrong change to it?
konstruct verify --why customer_ltv.lifetime_value --where customer_id=3  the source rows behind one value, each with its share
konstruct verify --effect --since v1.4                                    what each formula change since v1.4 does on today's data
konstruct verify --effect --timeline --since v1.4                         the timeline, with what each metric's change does on today's data
konstruct verify --laws                                                   the totals the lineage says must agree, checked per day
konstruct verify --laws --propose                                         the laws alone, reading no warehouse

lock

Pin what each upstream column this project reads means, in konstruct.lock.

konstruct lock [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--check]
               [--update [COLUMN ...]] [--no-write] [--no-history] [--format FORMAT] [--json]
               [--graph FILE] [--refresh] [--no-build]
               [NAME ...]
Positional Arguments
NAME

what to pin: columns, relations, exposures or terms (default: what konstruct.lock names, or every upstream column the project reads)

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--check

compare konstruct.lock with the build instead, and exit 1 when a pinned column changed

Default: False

--update

accept every change to the pinned columns, or the changes to these

--no-write

show what would be written, writing nothing

Default: False

--no-history

with –check, do not read git history for who changed what

Default: False

--format

Possible choices: text, markdown, json

text, markdown (with –check, for a pull request comment) or json

Default: 'text'

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct lock                            pin what each upstream column this project reads means
konstruct lock --check                    exit 1 when a pinned column means something else, and say what
konstruct lock --update main.ltv.total    accept a reviewed change to one pinned column
konstruct lock --check --format markdown  the check for a pull request comment

open

Open graph.html in a browser.

konstruct open [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--print-only]
               [--json] [--graph FILE] [--refresh] [--no-build]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--print-only

print the file URL without opening it

Default: False

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct open               graph.html in the default browser
konstruct open --print-only  print its file URL

install

Add the Konstruct skills and instructions to coding agents.

konstruct install [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                  [--agent AGENT [AGENT ...]] [--target DIR] [--mcp] [--force]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--agent

Possible choices: claude, cursor, codex, copilot, gemini, windsurf, both, all

claude, cursor, codex, copilot, gemini or windsurf; both (claude and cursor, the default) or all

Default: 'both'

--target

install into this repository, not your home directory

--mcp

also register the MCP server in each agent’s configuration

Default: False

--force

replace files and sections that were edited by hand

Default: False

Examples:

konstruct install                         the skills for Claude Code and Cursor, in your home directory
konstruct install --target . --mcp        into this repository, with the MCP server
konstruct install --target . --agent all  for every agent: Codex, Copilot, Gemini CLI too

hook

Check a data file a coding agent just edited, from its hook event on stdin (for agent hooks).

konstruct hook [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--remind]
               {post-edit}
Positional Arguments
event

Possible choices: post-edit

the hook event: post-edit, after a file edit

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--remind

only remind the agent to run the gate, without running it

Default: False

Examples:

konstruct hook post-edit  run by a Claude Code hook, with the hook's event on stdin

serve

Serve the viewer and a JSON API over the graph, reloading after each build.

konstruct serve [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--port PORT]
                [--host HOST] [--watch] [--open] [--no-build]
                [PROJECT]
Positional Arguments
PROJECT

project directory (default: -C or .)

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--port

port (default 8000; 0 for any free port)

Default: 8000

--host

address to listen on (default 127.0.0.1: this machine only)

Default: '127.0.0.1'

--watch

rebuild the graph when its inputs change

Default: False

--open

open the viewer in a browser

Default: False

--no-build

serve the graph as it is, if there is one

Default: False

Examples:

konstruct serve                      build, then serve the viewer and the HTTP API on 127.0.0.1:8000
konstruct serve --watch --open       rebuild as inputs change, and open the browser
konstruct serve --no-build --port 0  the graph as it is, on any free port

receipts

Record what an answer rests on, and check later whether it still holds.

konstruct receipts [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                   <action> ...
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

actions
<action>

Possible choices: issue, show, check

Sub-commands
issue

Record what an answer rests on, and print a citation for it.

konstruct receipts issue [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                         [--question TEXT] [--answer TEXT] [--json] [--graph FILE] [--refresh]
                         [--no-build]
                         NAME [NAME ...]
Positional Arguments
NAME

a column, relation, exposure or business term the answer rests on

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--question

the question answered, recorded as given

--answer

the answer given, recorded as given

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--refresh

update the graph first if its inputs changed

Default: False

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct receipts issue customers.customer_lifetime_value  what an answer about it rests on
konstruct receipts issue "Customer lifetime value" --json   a term and its columns, as JSON
show

Print one receipt as it was issued.

konstruct receipts show [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                        [--json] [--graph FILE]
                        ID
Positional Arguments
ID

a receipt id, or the start of one

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

--graph

use the receipts beside this graph.json instead of finding konstruct-out

Examples:

konstruct receipts show r-7f3a  one receipt, by its id or the start of it
check

Whether what each receipt rests on still holds (exits 1 when one does not).

konstruct receipts check [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins]
                         [--no-history] [--no-refresh] [--json] [--graph FILE] [--no-build]
                         [ID ...]
Positional Arguments
ID

only these receipts (default: every one)

Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--no-history

do not read git history to say who changed what

Default: False

--no-refresh

do not update a graph older than its inputs first; receipts are then unchecked

Default: False

--json

print JSON instead of text

Default: False

--graph

use this graph.json instead of finding konstruct-out

--no-build

fail rather than build a missing graph

Default: False

Examples:

konstruct receipts check                every receipt; exit 1 when one does not hold
konstruct receipts check r-7f3a --json  one receipt, as JSON

Examples:

konstruct receipts issue customer_ltv.lifetime_value --question "LTV of customer 3?"  record what an answer rests on
konstruct receipts show r-7f3a                                                        one receipt, by its id or the start of it
konstruct receipts check                                                              which answers rest on something that has changed since

mcp

Run the MCP server on stdio (for agent configuration, not interactive use).

konstruct mcp [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--no-prompts]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--no-prompts

offer the tools and resources without the workflow prompts

Default: False

Examples:

konstruct mcp  run by an agent from its configuration, not by hand

plugins

List installed plugins and whether each runs for this project.

konstruct plugins [-h] [-C DIR] [--no-color] [--trust-config] [-v] [-q] [--no-plugins] [--json]
Named Arguments
-C, --project, --path

project directory (default: the current directory)

--no-color, --no-colour

never colour the output (NO_COLOR is also respected)

--trust-config

trust the project for this command, as KONSTRUCT_TRUST_CONFIG=1 does

-v, --verbose

log progress to stderr

-q, --quiet

no progress messages on stderr

--no-plugins

run no plugins, whatever konstruct.toml enables (KONSTRUCT_NO_PLUGINS=1 also does)

--json

print JSON instead of text

Default: False

Examples:

konstruct plugins         installed plugins, and whether each runs for this project
konstruct plugins --json  the same as JSON

Examples:

konstruct build                             build the graph for the current directory
konstruct status                            what Konstruct finds here; is the graph current?
konstruct impact orders.amount              what breaks if orders.amount changes
konstruct trace customers.lifetime_value    where a value comes from
konstruct explain customers.lifetime_value  its formula, down to source columns
konstruct diff --base origin/main           what this branch changes and breaks, column by column
konstruct gate                              the check to pass before opening a pull request
konstruct install                           add the Konstruct skills to Claude Code and Cursor

Names can be a table (orders, main.orders), a column (orders.amount), a dbt unique id or a DAG task (dag_id.task_id). Query commands build the graph first if it does not exist yet. Run konstruct <command> --help for a command’s options and examples.