User guide

1. First graph in under a minute

npx lineagesutra-ai scan --root ./sql --out lineage.html

Open lineage.html. Read Unresolved or unsupported SQL first.

2. Ask what a change breaks

npx lineagesutra-ai scan --root ./sql --out lineage.json
npx lineagesutra-ai impact --input lineage.json --table customers --column email --change rename --out impact.html

3. Trace where a column comes from

npx lineagesutra-ai upstream --input lineage.json --table email_metrics --column address

4. Catch breaking changes in CI

lineagesutra scan --root sql --out new.json --strict
lineagesutra compare --before baseline.json --after new.json --fail-on-breaking --out drift.html

Exit code 3 fails the job. Publish the HTML as an artifact.

5. Make unknowns disappear

Most warnings are column-unknown: a SELECT * or unqualified column over a table whose CREATE TABLE is not in the scanned folder. Add the DDL to the folder and re-scan.

6. Audit

npx lineagesutra-ai audit --root ./sql --out audit-out

Open audit-out/audit-report.html. Share the .md in a pull request.

7. Use with AI tools

npx lineagesutra-ai install-skills --ide claude --project .
npx lineagesutra-ai mcp --root ./sql

Troubleshooting

SymptomFix
--root is requiredPass the folder with .sql files
TARGET_NOT_FOUNDTable name not in the graph; check case and schema prefix
Many unsupported warningsTemplated or dynamic SQL; compile dbt models first and scan the compiled folder
integrity invalidReport was edited; re-run the scan
Exit 3A gate you requested tripped; read the report