0
# Command Line Interface
1

2
Command-line tools for validating YAML files in scripts and automated workflows. The Yamale CLI provides powerful file validation capabilities with support for batch processing, custom schemas, and flexible output options.
3

4
## Capabilities
5

6
### Basic Command Usage
7

8
The `yamale` command validates YAML files against schemas with automatic schema discovery.
9

10
```bash { .api }
11
yamale [options] [PATH ...]
12
```
13

14
### Command Line Options
15

16
```bash { .api }
17
# Core options
18
-h, --help              # Show help message and exit
19
-s SCHEMA, --schema SCHEMA    # Schema filename (default: schema.yaml)
20
-V, --version          # Show program version and exit
21

22
# File processing
23
-e PATTERN, --exclude PATTERN # Python regex to exclude files (can be used multiple times)
24
-p PARSER, --parser PARSER    # YAML parser: "pyyaml" (default) or "ruamel"
25

26
# Validation modes  
27
-x, --no-strict        # Disable strict mode (allow unexpected elements)
28
-v, --verbose          # Show verbose output
29

30
# Performance
31
-n CPU_NUM, --cpu-num CPU_NUM # Number of processes for validation (default: 4, or 'auto')
32
```
33

34
## Basic Usage Examples
35

36
### Single File Validation
37

38
```bash
39
# Validate single file with default schema (schema.yaml)
40
yamale data.yaml
41

42
# Use custom schema file
43
yamale -s user-schema.yaml user-data.yaml
44

45
# Validate with verbose output
46
yamale -v config.yaml
47
```
48

49
### Directory Validation
50

51
```bash
52
# Validate all YAML files in current directory
53
yamale
54

55
# Validate all YAML files in specific directory  
56
yamale ./configs/
57

58
# Validate multiple directories
59
yamale ./api-specs/ ./configurations/ ./test-data/
60
```
61

62
### Schema Discovery
63

64
Yamale automatically searches for schema files:
65

66
1. Same directory as the data file
67
2. Parent directories (recursive search up the tree)
68
3. Uses first schema file found
69
4. Reports error if no schema found
70

71
```bash
72
# Directory structure:
73
# project/
74
#   ├── schema.yaml          # Found for any file in project/
75
#   ├── config.yaml
76
#   └── data/
77
#       ├── local-schema.yaml # Found for files in data/
78
#       ├── users.yaml        # Uses data/local-schema.yaml
79
#       └── settings.yaml     # Uses data/local-schema.yaml
80

81
yamale project/config.yaml      # Uses project/schema.yaml
82
yamale project/data/users.yaml  # Uses project/data/local-schema.yaml
83
```
84

85
### Advanced Usage
86

87
#### Pattern Exclusion
88

89
```bash
90
# Exclude test files
91
yamale -e "test.*\.yaml$" ./configs/
92

93
# Exclude multiple patterns
94
yamale -e "\.tmp$" -e "backup.*" -e "draft.*" ./data/
95

96
# Exclude sensitive files
97
yamale -e "secret" -e "private" -e "\.key$" ./
98
```
99

100
#### Parser Selection
101

102
```bash
103
# Use ruamel.yaml for YAML 1.2 support
104
yamale -p ruamel schema.yaml data.yaml
105

106
# Default PyYAML parser
107
yamale -p pyyaml schema.yaml data.yaml
108
```
109

110
#### Performance Tuning
111

112
```bash
113
# Use all available CPU cores
114
yamale -n auto ./large-dataset/
115

116
# Limit to 2 processes
117
yamale -n 2 ./configs/
118

119
# Single-threaded processing
120
yamale -n 1 ./data/
121
```
122

123
#### Strict Mode Control
124

125
```bash
126
# Allow extra fields in data (non-strict mode)
127
yamale -x config.yaml
128

129
# Default strict mode (reject extra fields)
130
yamale config.yaml
131
```
132

133
## Practical Examples
134

135
### CI/CD Integration
136

137
```bash
138
#!/bin/bash
139
# validate-configs.sh - CI validation script
140

141
echo "Validating configuration files..."
142

143
# Validate production configs with strict mode
144
if yamale -s prod-schema.yaml configs/prod/*.yaml; then
145
    echo "✓ Production configs valid"
146
else
147
    echo "✗ Production config validation failed"
148
    exit 1
149
fi
150

151
# Validate development configs (allow extra fields)
152
if yamale -x -s dev-schema.yaml configs/dev/*.yaml; then
153
    echo "✓ Development configs valid"  
154
else
155
    echo "✗ Development config validation failed"
156
    exit 1
157
fi
158

159
# Validate API specifications
160
if yamale -s api-schema.yaml -e "\.draft\.yaml$" api-specs/; then
161
    echo "✓ API specifications valid"
162
else
163
    echo "✗ API specification validation failed"
164
    exit 1
165
fi
166

167
echo "All validations passed!"
168
```
169

170
### Bulk Validation Script
171

172
```bash
173
#!/bin/bash
174
# bulk-validate.sh - Validate multiple projects
175

176
PROJECTS=("project-a" "project-b" "project-c")
177
TOTAL=0
178
PASSED=0
179

180
for project in "${PROJECTS[@]}"; do
181
    echo "Validating $project..."
182
    TOTAL=$((TOTAL + 1))
183
    
184
    if yamale -s schemas/${project}-schema.yaml data/${project}/; then
185
        echo "✓ $project passed"
186
        PASSED=$((PASSED + 1))
187
    else
188
        echo "✗ $project failed"
189
    fi
190
done
191

192
echo "Results: $PASSED/$TOTAL projects passed validation"
193

194
if [ $PASSED -eq $TOTAL ]; then
195
    echo "All projects validated successfully!"
196
    exit 0
197
else
198
    echo "Some projects failed validation"
199
    exit 1
200
fi
201
```
202

203
### Pre-commit Hook
204

205
```bash
206
#!/bin/bash
207
# .git/hooks/pre-commit
208

209
echo "Running YAML validation..."
210

211
# Get list of staged YAML files
212
YAML_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.ya\?ml$')
213

214
if [ -z "$YAML_FILES" ]; then
215
    echo "No YAML files to validate"
216
    exit 0
217
fi
218

219
# Validate each file
220
for file in $YAML_FILES; do
221
    echo "Validating $file..."
222
    if ! yamale -s .yamale-schema.yaml "$file"; then
223
        echo "❌ Validation failed for $file"
224
        echo "Please fix validation errors before committing"
225
        exit 1
226
    fi
227
done
228

229
echo "✅ All YAML files validated successfully"
230
exit 0
231
```
232

233
### Development Workflow
234

235
```bash
236
# Development validation with verbose output
237
yamale -v -s dev-schema.yaml config-dev.yaml
238

239
# Quick validation during development (non-strict)
240
yamale -x config.yaml
241

242
# Validate before deployment (strict + performance)
243
yamale -n auto -s prod-schema.yaml configs/prod/
244

245
# Validate with specific exclusions
246
yamale -e "\.backup$" -e "\.tmp$" -s schema.yaml ./
247
```
248

249
## Exit Codes
250

251
The `yamale` command returns standard exit codes:
252

253
- **0**: All validations passed successfully
254
- **1**: One or more validations failed
255
- **2**: Command line argument errors
256
- **3**: File not found or permission errors
257

258
```bash
259
# Check exit code in scripts
260
yamale config.yaml
261
if [ $? -eq 0 ]; then
262
    echo "Validation passed"
263
else
264
    echo "Validation failed"
265
fi
266

267
# Use in conditional statements
268
if yamale -s schema.yaml data.yaml; then
269
    deploy_application
270
else
271
    echo "Cannot deploy: validation failed"
272
    exit 1
273
fi
274
```
275

276
## Output Format
277

278
### Default Output
279

280
```
281
# Successful validation (no output)
282
$ yamale config.yaml
283
$ echo $?
284
0
285

286
# Failed validation
287
$ yamale invalid.yaml
288
Error validating data 'invalid.yaml' with 'schema.yaml'
289
    name: Required field missing
290
    age: '25.5' is not an integer
291
$ echo $?
292
1
293
```
294

295
### Verbose Output
296

297
```bash
298
$ yamale -v config.yaml
299
Loading schema: schema.yaml
300
Loading data: config.yaml
301
Validating config.yaml against schema.yaml
302
Validation successful: config.yaml
303
```
304

305
### Multiple File Output
306

307
```
308
$ yamale configs/
309
Error validating data 'configs/invalid.yaml' with 'configs/schema.yaml'
310
    database.port: '3306.5' is not an integer
311
    
312
Error validating data 'configs/incomplete.yaml' with 'configs/schema.yaml'  
313
    api.key: Required field missing
314
    
315
2 of 5 files failed validation
316
```
317

318
## Integration Examples
319

320
### Make Integration
321

322
```makefile
323
# Makefile
324
.PHONY: validate-yaml validate-prod validate-dev
325

326
validate-yaml: validate-dev validate-prod
327

328
validate-dev:
329
	@echo "Validating development configs..."
330
	yamale -x -s schemas/dev-schema.yaml configs/dev/
331

332
validate-prod:
333
	@echo "Validating production configs..."
334
	yamale -s schemas/prod-schema.yaml configs/prod/
335

336
deploy: validate-prod
337
	@echo "Configs validated, deploying..."
338
	# deployment commands here
339
```
340

341
### Docker Integration
342

343
```dockerfile
344
# Dockerfile
345
FROM python:3.11-slim
346

347
# Install yamale
348
RUN pip install yamale
349

350
# Copy schemas and data
351
COPY schemas/ /app/schemas/
352
COPY data/ /app/data/
353

354
WORKDIR /app
355

356
# Validate on container start
357
CMD ["yamale", "-s", "schemas/app-schema.yaml", "data/"]
358
```
359

360
### GitHub Actions
361

362
```yaml
363
# .github/workflows/validate.yml
364
name: YAML Validation
365

366
on: [push, pull_request]
367

368
jobs:
369
  validate:
370
    runs-on: ubuntu-latest
371
    steps:
372
    - uses: actions/checkout@v3
373
    
374
    - name: Set up Python
375
      uses: actions/setup-python@v4
376
      with:
377
        python-version: '3.11'
378
    
379
    - name: Install yamale
380
      run: pip install yamale
381
    
382
    - name: Validate YAML files
383
      run: |
384
        yamale -s .github/schemas/config-schema.yaml configs/
385
        yamale -s .github/schemas/api-schema.yaml api-specs/
386
```