0
# CLI Tools
1

2
Command-line utilities for batch processing, validation, formatting, and migration of Mapbox GL style files. These tools enable automation workflows and integration with build systems.
3

4
## Available Commands
5

6
The package provides four CLI tools accessible after installation:
7

8
- `gl-style-validate` - Validate style files against specification
9
- `gl-style-format` - Format and prettify style JSON files  
10
- `gl-style-migrate` - Migrate older style versions to current specification
11
- `gl-style-composite` - Composite multiple vector sources into single source
12

13
## Installation and Access
14

15
```bash
16
npm install -g @mapbox/mapbox-gl-style-spec
17

18
# Or use with npx without global installation
19
npx @mapbox/mapbox-gl-style-spec <command>
20
```
21

22
## Capabilities
23

24
### Style Validation Tool
25

26
Validates Mapbox GL style files against the specification with detailed error reporting.
27

28
**Command:** `gl-style-validate`
29

30
**Usage:**
31
```bash
32
gl-style-validate [options] <style-file>
33
```
34

35
**Options:**
36
- `--json` - Output errors in JSON format instead of human-readable text
37
- `--mapbox-api-supported` - Validate Mapbox API compatibility (checks for unsupported features)
38

39
**Examples:**
40

41
```bash
42
# Basic validation
43
gl-style-validate my-style.json
44

45
# JSON output for programmatic processing
46
gl-style-validate --json my-style.json
47

48
# Check Mapbox API compatibility
49
gl-style-validate --mapbox-api-supported my-style.json
50

51
# Combine options
52
gl-style-validate --json --mapbox-api-supported my-style.json
53
```
54

55
**Exit Codes:**
56
- `0` - Style is valid
57
- `1` - Style has validation errors
58

59
**Output Format:**
60

61
Human-readable (default):
62
```
63
✓ Style is valid
64
```
65

66
JSON format (`--json`):
67
```json
68
{
69
  "valid": true,
70
  "errors": []
71
}
72
```
73

74
With errors:
75
```json
76
{
77
  "valid": false,
78
  "errors": [
79
    {
80
      "message": "layers[0]: missing required property \"type\"",
81
      "line": 12
82
    }
83
  ]
84
}
85
```
86

87
### Style Formatting Tool
88

89
Formats style JSON files with proper key ordering and consistent indentation.
90

91
**Command:** `gl-style-format`
92

93
**Usage:**
94
```bash
95
gl-style-format [options] <style-file>
96
```
97

98
**Options:**
99
- `--space <number>` - Number of spaces for indentation (default: 2, use 0 for minified output)
100

101
**Examples:**
102

103
```bash
104
# Format with default 2-space indentation
105
gl-style-format my-style.json
106

107
# Format with 4-space indentation
108
gl-style-format --space 4 my-style.json
109

110
# Minify (single line, no formatting)
111
gl-style-format --space 0 my-style.json
112

113
# Format and save to new file
114
gl-style-format my-style.json > formatted-style.json
115
```
116

117
**Key Ordering:**
118

119
The formatter ensures consistent key ordering for better diffing and version control:
120

121
1. `version`
122
2. `name`
123
3. `metadata`
124
4. `sources`
125
5. `sprite`
126
6. `glyphs`
127
7. `layers`
128
8. `transition`
129
9. `light`/`lights`
130
10. `terrain`
131
11. `fog`
132

133
### Style Migration Tool
134

135
Migrates older style versions to the current specification format.
136

137
**Command:** `gl-style-migrate`
138

139
**Usage:**
140
```bash
141
gl-style-migrate <style-file>
142
```
143

144
**Supported Migrations:**
145
- Mapbox GL v7 styles to v8
146
- Legacy function syntax to expression syntax
147
- Deprecated property names to current equivalents
148

149
**Examples:**
150

151
```bash
152
# Migrate v7 style to v8
153
gl-style-migrate v7-style.json
154

155
# Migrate and save to new file
156
gl-style-migrate old-style.json > migrated-style.json
157
```
158

159
**Migration Changes:**
160
- Updates `version` field from 7 to 8
161
- Converts function-based properties to expressions
162
- Updates deprecated layer types and properties
163
- Modernizes filter syntax
164
- Updates source configurations for v8 compatibility
165

166
### Source Composition Tool
167

168
Composites multiple Mapbox vector sources into a single optimized source.
169

170
**Command:** `gl-style-composite`
171

172
**Usage:**
173
```bash
174
gl-style-composite <style-file>
175
```
176

177
**Examples:**
178

179
```bash
180
# Composite vector sources
181
gl-style-composite multi-source-style.json
182

183
# Composite and save result
184
gl-style-composite style.json > composited-style.json
185
```
186

187
**Compositing Process:**
188
- Identifies multiple Mapbox vector tile sources
189
- Combines them into a single composite source
190
- Updates layer source references
191
- Optimizes for reduced HTTP requests
192

193
## Integration Examples
194

195
### Build System Integration
196

197
**package.json scripts:**
198
```json
199
{
200
  "scripts": {
201
    "validate-styles": "gl-style-validate src/styles/*.json",
202
    "format-styles": "gl-style-format --space 2 src/styles/*.json",
203
    "migrate-styles": "gl-style-migrate legacy-styles/*.json",
204
    "build-styles": "npm run migrate-styles && npm run format-styles && npm run validate-styles"
205
  }
206
}
207
```
208

209
### CI/CD Pipeline
210

211
**.github/workflows/styles.yml:**
212
```yaml
213
name: Style Validation
214
on: [push, pull_request]
215

216
jobs:
217
  validate:
218
    runs-on: ubuntu-latest
219
    steps:
220
      - uses: actions/checkout@v2
221
      - uses: actions/setup-node@v2
222
        with:
223
          node-version: '16'
224
      - run: npm install -g @mapbox/mapbox-gl-style-spec
225
      - run: gl-style-validate --json styles/*.json
226
```
227

228
### Batch Processing
229

230
```bash
231
#!/bin/bash
232
# Process all style files in a directory
233

234
STYLE_DIR="./styles"
235
OUTPUT_DIR="./processed-styles"
236

237
mkdir -p "$OUTPUT_DIR"
238

239
for style in "$STYLE_DIR"/*.json; do
240
    filename=$(basename "$style")
241
    echo "Processing $filename..."
242
    
243
    # Migrate, format, and validate
244
    gl-style-migrate "$style" | \
245
    gl-style-format --space 2 > "$OUTPUT_DIR/$filename"
246
    
247
    # Validate the result
248
    if gl-style-validate "$OUTPUT_DIR/$filename"; then
249
        echo "✓ $filename processed successfully"
250
    else
251
        echo "✗ $filename has validation errors"
252
    fi
253
done
254
```
255

256
### Programmatic Usage
257

258
While these are CLI tools, you can also invoke them programmatically:
259

260
```javascript
261
const { execSync } = require('child_process');
262

263
function validateStyle(stylePath) {
264
  try {
265
    const result = execSync(`gl-style-validate --json "${stylePath}"`, {
266
      encoding: 'utf8'
267
    });
268
    return JSON.parse(result);
269
  } catch (error) {
270
    // Handle validation errors
271
    return JSON.parse(error.stdout);
272
  }
273
}
274

275
function formatStyle(stylePath, spaces = 2) {
276
  return execSync(`gl-style-format --space ${spaces} "${stylePath}"`, {
277
    encoding: 'utf8'
278
  });
279
}
280
```
281

282
## Error Handling
283

284
All CLI tools use standard exit codes and provide detailed error messages:
285

286
**Exit Codes:**
287
- `0` - Success
288
- `1` - Validation/processing errors
289
- `2` - Invalid command line arguments
290

291
**Common Error Scenarios:**
292

293
1. **File Not Found:**
294
```bash
295
$ gl-style-validate nonexistent.json
296
Error: ENOENT: no such file or directory, open 'nonexistent.json'
297
```
298

299
2. **Invalid JSON:**
300
```bash
301
$ gl-style-validate invalid.json
302
Error: Unexpected token } in JSON at position 123
303
```
304

305
3. **Validation Errors:**
306
```bash
307
$ gl-style-validate --json invalid-style.json
308
{
309
  "valid": false,
310
  "errors": [
311
    {"message": "sources: required property missing", "line": 1}
312
  ]
313
}
314
```
315

316
## Performance Considerations
317

318
- **Large Files**: Tools handle large style files efficiently but may require additional memory
319
- **Batch Processing**: Use shell loops or build tools for processing multiple files
320
- **JSON Parsing**: Tools use optimized JSON parsing with detailed error location reporting
321
- **Validation Caching**: Consider caching validation results for unchanged files in build systems