0
# CLI Usage
1

2
Command-line interface for formatting SQL files and integrating with development workflows.
3

4
## Installation
5

6
Install the CLI tool globally or use with npx:
7

8
```bash
9
# Global installation
10
npm install -g sql-formatter
11

12
# Or use with npx (no installation required)
13
npx sql-formatter --help
14
```
15

16
## Command Syntax
17

18
```bash
19
sql-formatter [-h] [-o OUTPUT] [--fix] 
20
              [-l LANGUAGE] [-c CONFIG] [--version] [FILE]
21
```
22

23
## Options
24

25
### Basic Options
26

27
```bash { .api }
28
# Show help message
29
sql-formatter -h
30
sql-formatter --help
31

32
# Show version number  
33
sql-formatter --version
34
```
35

36
### Input/Output Options
37

38
```bash { .api }
39
# Format file and output to stdout
40
sql-formatter input.sql
41

42
# Format from stdin
43
echo "SELECT * FROM users" | sql-formatter
44

45
# Specify output file
46
sql-formatter input.sql -o formatted.sql
47
sql-formatter input.sql --output formatted.sql
48

49
# Update file in-place
50
sql-formatter input.sql --fix
51
```
52

53
### Language Options
54

55
```bash { .api }
56
# Specify SQL dialect
57
sql-formatter -l mysql input.sql
58
sql-formatter --language postgresql input.sql
59

60
# Available languages:
61
# bigquery, db2, db2i, duckdb, hive, mariadb, mysql, n1ql, plsql, 
62
# postgresql, redshift, singlestoredb, snowflake, spark, sql, 
63
# sqlite, tidb, transactsql, trino, tsql
64
```
65

66
### Configuration Options
67

68
```bash { .api }
69
# Specify config file
70
sql-formatter -c .sql-formatter.json input.sql
71
sql-formatter --config config.json input.sql
72

73
# Specify config as JSON string
74
sql-formatter -c '{"keywordCase":"upper","tabWidth":4}' input.sql
75
```
76

77
## Usage Examples
78

79
### Basic Formatting
80

81
```bash
82
# Format a single file
83
sql-formatter query.sql
84

85
# Format from stdin
86
echo "select * from users where active=1" | sql-formatter
87

88
# Format with specific dialect
89
sql-formatter --language mysql query.sql
90
```
91

92
### File Operations
93

94
```bash
95
# Format and save to new file
96
sql-formatter input.sql --output formatted.sql
97

98
# Update file in-place
99
sql-formatter query.sql --fix
100

101
# Process multiple files (using shell)
102
for file in *.sql; do
103
  sql-formatter "$file" --fix
104
done
105
```
106

107
### Configuration Examples
108

109
```bash
110
# Use custom configuration file
111
sql-formatter --config .sql-formatter.json query.sql
112

113
# Inline configuration
114
sql-formatter -c '{"keywordCase":"upper","indentStyle":"tabularLeft"}' query.sql
115

116
# Combined language and config
117
sql-formatter --language postgresql --config config.json query.sql
118
```
119

120
## Configuration File
121

122
The CLI automatically looks for `.sql-formatter.json` in the current directory and parent directories.
123

124
**Example `.sql-formatter.json`:**
125

126
```json
127
{
128
  "language": "mysql",
129
  "keywordCase": "upper", 
130
  "identifierCase": "lower",
131
  "tabWidth": 4,
132
  "indentStyle": "standard",
133
  "linesBetweenQueries": 2
134
}
135
```
136

137
**Configuration Search Order:**
138

139
1. File specified with `--config` option
140
2. JSON string passed to `--config` option  
141
3. `.sql-formatter.json` in current directory
142
4. `.sql-formatter.json` in parent directories (recursive search)
143
5. Default configuration
144

145
## Integration Examples
146

147
### Git Hooks
148

149
Format SQL files before commit:
150

151
```bash
152
# .git/hooks/pre-commit
153
#!/bin/sh
154
for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.sql$'); do
155
  sql-formatter "$file" --fix
156
  git add "$file"
157
done
158
```
159

160
### NPM Scripts
161

162
Add to `package.json`:
163

164
```json
165
{
166
  "scripts": {
167
    "format:sql": "sql-formatter --fix src/**/*.sql",
168
    "check:sql": "sql-formatter --config .sql-formatter.json src/**/*.sql"
169
  }
170
}
171
```
172

173
### CI/CD Pipeline
174

175
GitHub Actions example:
176

177
```yaml
178
- name: Format SQL files
179
  run: |
180
    npm install -g sql-formatter
181
    sql-formatter --fix database/migrations/*.sql
182
    
183
- name: Check SQL formatting
184
  run: |
185
    sql-formatter --config .sql-formatter.json database/**/*.sql > /dev/null
186
    if [ $? -ne 0 ]; then
187
      echo "SQL files are not properly formatted"
188
      exit 1
189
    fi
190
```
191

192
### Build Tools
193

194
#### Webpack Integration
195

196
```javascript
197
const { execSync } = require('child_process');
198

199
module.exports = {
200
  // ... webpack config
201
  plugins: [
202
    {
203
      apply: (compiler) => {
204
        compiler.hooks.beforeCompile.tap('FormatSQL', () => {
205
          execSync('sql-formatter --fix src/**/*.sql');
206
        });
207
      }
208
    }
209
  ]
210
};
211
```
212

213
#### Gulp Integration
214

215
```javascript
216
const { exec } = require('child_process');
217
const gulp = require('gulp');
218

219
gulp.task('format-sql', (cb) => {
220
  exec('sql-formatter --fix src/**/*.sql', cb);
221
});
222
```
223

224
## Error Handling
225

226
The CLI provides helpful error messages for common issues:
227

228
```bash
229
# File not found
230
sql-formatter nonexistent.sql
231
# Error: could not open file nonexistent.sql
232

233
# No input provided
234
sql-formatter
235
# Error: no file specified and no data in stdin
236

237
# Invalid configuration
238
sql-formatter -c '{"invalid": json}' query.sql  
239
# Error: unable to parse as JSON or treat as JSON file
240

241
# Conflicting options
242
sql-formatter --output out.sql --fix input.sql
243
# Error: Cannot use both --output and --fix options simultaneously
244

245
# Missing file for --fix
246
sql-formatter --fix
247
# Error: The --fix option cannot be used without a filename
248
```
249

250
## Exit Codes
251

252
- `0` - Success
253
- `1` - Error (invalid input, configuration, or file system error)
254

255
## Performance Tips
256

257
For large files or batch processing:
258

259
```bash
260
# Process files in parallel (if using GNU parallel)
261
find . -name "*.sql" | parallel sql-formatter {} --fix
262

263
# Use specific language to avoid detection overhead
264
sql-formatter --language mysql large-file.sql
265

266
# Use configuration file instead of inline JSON for repeated use
267
sql-formatter --config .sql-formatter.json query.sql
268
```