0
# CLI Interface
1

2
Command-line interface for analyzing SQL files and generating lineage reports, with options for different output formats and visualization modes. The CLI provides a convenient way to perform lineage analysis without writing Python code.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
```python { .api }
9
def main(args=None) -> None:
10
    """
11
    The command line interface entry point.
12

13
    Parameters:
14
    - args: command line arguments for sqllineage command (optional)
15
    """
16
```
17

18
### Console Script
19

20
The package installs a console script entry point:
21

22
```bash
23
sqllineage = sqllineage.cli:main
24
```
25

26
## Command Line Arguments
27

28
### Input Options
29

30
```bash
31
# SQL from command line
32
sqllineage -e "SELECT * FROM customers"
33

34
# SQL from file
35
sqllineage -f queries.sql
36

37
# Multiple files
38
sqllineage -f query1.sql -f query2.sql
39
```
40

41
### Output Control
42

43
```bash
44
# Verbose mode - show statement level lineage
45
sqllineage -v -e "SELECT * FROM customers"
46

47
# Set lineage level (table or column)
48
sqllineage -l table -f queries.sql
49
sqllineage -l column -f queries.sql
50
```
51

52
### Visualization Options
53

54
```bash
55
# Launch graph visualization
56
sqllineage -g -f queries.sql
57

58
# Specify visualization server host and port
59
sqllineage -g -H 0.0.0.0 -p 8080 -f queries.sql
60
```
61

62
### SQL Dialect Options
63

64
```bash
65
# Specify SQL dialect
66
sqllineage -d snowflake -f snowflake_queries.sql
67
sqllineage -d postgres -f postgres_queries.sql
68

69
# List available dialects
70
sqllineage --dialects
71
```
72

73
### Error Handling
74

75
```bash
76
# Silent mode - skip unsupported statements
77
sqllineage --silent_mode -f mixed_queries.sql
78
```
79

80
### Metadata Integration
81

82
```bash
83
# Use SQLAlchemy metadata provider
84
sqllineage --sqlalchemy_url "postgresql://user:pass@host/db" -f queries.sql
85
```
86

87
## Complete Argument Reference
88

89
| Argument | Short | Type | Description |
90
|----------|-------|------|-------------|
91
| `--version` | | flag | Show version and exit |
92
| `-e <sql>` | `-e` | string | SQL from command line |
93
| `-f <filename>` | `-f` | string | SQL from files (can be repeated) |
94
| `--verbose` | `-v` | flag | Show statement level lineage result |
95
| `--level <level>` | `-l` | choice | Lineage level: table or column |
96
| `--graph-visualization` | `-g` | flag | Show graph visualization |
97
| `--host <host>` | `-H` | string | Visualization webserver host (default: localhost) |
98
| `--port <port>` | `-p` | integer | Visualization webserver port (default: 5000) |
99
| `--dialect <dialect>` | `-d` | string | SQL dialect (default: ansi) |
100
| `--dialects` | | flag | List available dialects |
101
| `--silent_mode` | | flag | Skip unsupported statements |
102
| `--sqlalchemy_url <url>` | | string | SQLAlchemy URL for metadata |
103
104
## Usage Examples
105

106
### Basic Table Lineage Analysis
107

108
```bash
109
# Analyze a single SQL statement
110
sqllineage -e "INSERT INTO summary SELECT * FROM details"
111

112
# Output:
113
# <default>.details
114
# =================
115
# <default>.summary
116
```
117

118
### File-Based Analysis
119

120
```bash
121
# Create a SQL file
122
cat > analysis.sql << 'EOF'
123
CREATE TABLE staging.customers AS
124
SELECT 
125
    customer_id,
126
    customer_name,
127
    email
128
FROM raw.customer_data
129
WHERE active = 'Y';
130

131
INSERT INTO analytics.customer_summary
132
SELECT 
133
    customer_id,
134
    customer_name,
135
    COUNT(*) as interaction_count
136
FROM staging.customers c
137
JOIN raw.interactions i ON c.customer_id = i.customer_id
138
GROUP BY customer_id, customer_name;
139
EOF
140

141
# Analyze the file
142
sqllineage -f analysis.sql
143
```
144

145
### Verbose Output
146

147
```bash
148
sqllineage -v -f analysis.sql
149

150
# Output includes statement-level breakdown:
151
# ************** Statement #1 **************
152
# CREATE TABLE staging.customers AS SELECT customer_id, customer_name, email FROM raw.customer_data WHERE active = 'Y'
153
# raw.customer_data
154
# =================
155
# staging.customers
156
# 
157
# ************** Statement #2 **************  
158
# INSERT INTO analytics.customer_summary SELECT customer_id, customer_name, COUNT(*) as interaction_count FROM staging.customers c JOIN raw.interactions i ON c.customer_id = i.customer_id GROUP BY customer_id, customer_name
159
# staging.customers
160
# raw.interactions
161
# =================
162
# analytics.customer_summary
163
```
164

165
### Column-Level Lineage
166

167
```bash
168
sqllineage -l column -f analysis.sql
169

170
# Output shows column-level relationships:
171
# raw.customer_data.customer_id -> staging.customers.customer_id
172
# raw.customer_data.customer_name -> staging.customers.customer_name
173
# raw.customer_data.email -> staging.customers.email
174
# staging.customers.customer_id -> analytics.customer_summary.customer_id
175
# staging.customers.customer_name -> analytics.customer_summary.customer_name
176
```
177

178
### Dialect-Specific Analysis
179

180
```bash
181
# List available SQL dialects
182
sqllineage --dialects
183

184
# Output:
185
# {
186
#   "sqlparse": ["non-validating"],
187
#   "sqlfluff": ["ansi", "bigquery", "clickhouse", "databricks", "db2", "duckdb", "exasol", "hive", "materialize", "mysql", "oracle", "postgres", "redshift", "snowflake", "soql", "sparksql", "sqlite", "teradata", "trino", "tsql"]
188
# }
189

190
# Analyze Snowflake SQL
191
sqllineage -d snowflake -e "CREATE OR REPLACE TABLE analytics.daily_sales AS SELECT DATE_TRUNC('DAY', order_timestamp) as sale_date, SUM(amount) as daily_revenue FROM raw.transactions GROUP BY DATE_TRUNC('DAY', order_timestamp)"
192
```
193

194
### Web Visualization
195

196
```bash
197
# Launch web visualization (opens browser)
198
sqllineage -g -f complex_queries.sql
199

200
# Specify custom host/port for visualization
201
sqllineage -g -H 0.0.0.0 -p 8080 -f queries.sql
202
```
203

204
### Database Metadata Integration
205

206
```bash
207
# PostgreSQL metadata
208
sqllineage --sqlalchemy_url "postgresql://analyst:password@db.company.com:5432/analytics" -l column -f postgres_queries.sql
209

210
# Snowflake metadata
211
sqllineage --sqlalchemy_url "snowflake://user:password@account/database/schema" -d snowflake -l column -f snowflake_queries.sql
212

213
# MySQL metadata
214
sqllineage --sqlalchemy_url "mysql://user:password@localhost:3306/analytics" -d mysql -f mysql_queries.sql
215
```
216

217
### Error Handling and Silent Mode
218

219
```bash
220
# Create mixed SQL file with supported and unsupported statements
221
cat > mixed.sql << 'EOF'
222
-- Supported
223
CREATE VIEW sales_view AS SELECT * FROM sales;
224

225
-- Unsupported (DDL permissions)
226
GRANT SELECT ON sales_view TO analyst_role;
227

228
-- Supported
229
INSERT INTO summary SELECT customer_id, SUM(amount) FROM sales_view GROUP BY customer_id;
230

231
-- Unsupported (procedural)
232
CREATE PROCEDURE update_summary() AS BEGIN UPDATE summary SET last_updated = NOW(); END;
233
EOF
234

235
# Normal mode (shows errors)
236
sqllineage -f mixed.sql
237

238
# Silent mode (skips unsupported statements)
239
sqllineage --silent_mode -f mixed.sql
240
```
241

242
### Complex Analysis Pipeline
243

244
```bash
245
# Multi-step analysis with different outputs
246
echo "CREATE TABLE mart.customer_360 AS 
247
SELECT 
248
    c.customer_id,
249
    c.customer_name,
250
    p.total_purchases,
251
    s.support_tickets,
252
    m.email_engagement
253
FROM raw.customers c
254
LEFT JOIN analytics.purchase_summary p ON c.customer_id = p.customer_id  
255
LEFT JOIN analytics.support_summary s ON c.customer_id = s.customer_id
256
LEFT JOIN analytics.marketing_summary m ON c.customer_id = m.customer_id" > customer_360.sql
257

258
# Table-level analysis
259
echo "=== TABLE LINEAGE ==="
260
sqllineage -f customer_360.sql
261

262
# Column-level analysis  
263
echo -e "\n=== COLUMN LINEAGE ==="
264
sqllineage -l column -f customer_360.sql
265

266
# Verbose analysis
267
echo -e "\n=== VERBOSE ANALYSIS ==="
268
sqllineage -v -f customer_360.sql
269

270
# Launch visualization
271
sqllineage -g -f customer_360.sql
272
```
273

274
### Environment Integration
275

276
```bash
277
# Set default schema via environment
278
export SQLLINEAGE_DEFAULT_SCHEMA="analytics"
279

280
# Analyze unqualified table references
281
sqllineage -e "SELECT * FROM customers"  # Interprets as analytics.customers
282

283
# Override with different dialect
284
sqllineage -d postgres -e "SELECT customer_id, email FROM users WHERE created_date >= CURRENT_DATE - INTERVAL '30 days'"
285
```
286

287
### Batch Processing
288

289
```bash
290
# Process multiple SQL files
291
for file in queries/*.sql; do
292
    echo "=== Analyzing $file ==="
293
    sqllineage -f "$file"
294
    echo
295
done
296

297
# Generate lineage reports for all files
298
mkdir -p reports
299
for file in queries/*.sql; do
300
    basename=$(basename "$file" .sql)
301
    sqllineage -v -f "$file" > "reports/${basename}_lineage.txt"
302
done
303
```
304

305
### Integration with CI/CD
306

307
```bash
308
#!/bin/bash
309
# lineage_check.sh - CI script to validate SQL lineage
310

311
set -e
312

313
echo "Validating SQL lineage in migration files..."
314

315
# Check for unsupported SQL patterns
316
if ! sqllineage --silent_mode -f migrations/*.sql > /dev/null 2>&1; then
317
    echo "ERROR: SQL lineage analysis failed"
318
    exit 1
319
fi
320

321
# Generate lineage documentation
322
sqllineage -v -f migrations/*.sql > docs/lineage_report.txt
323

324
echo "SQL lineage validation completed successfully"
325
```