0
# Command Line Interface
1

2
PyKwalify provides CLI functionality for validating YAML/JSON files from the command line with support for extensions, encoding options, and various validation flags.
3

4
## Capabilities
5

6
### CLI Functions
7

8
```python { .api }
9
def parse_cli():
10
    """
11
    Parse command line arguments using docopt.
12
    
13
    Returns:
14
        dict: Parsed command line arguments
15
    """
16

17
def run(cli_args):
18
    """
19
    Execute validation with parsed CLI arguments.
20
    
21
    Args:
22
        cli_args (dict): Parsed command line arguments from parse_cli()
23
    
24
    Returns:
25
        int: Exit code (0 for success, non-zero for errors)
26
    """
27

28
def cli_entrypoint():
29
    """
30
    Main CLI entry point function.
31
    Called when 'pykwalify' command is executed.
32
    """
33
```
34

35
## Command Line Usage
36

37
### Basic Syntax
38

39
```bash
40
pykwalify -d FILE -s FILE ... [-e FILE ...]
41
          [--strict-rule-validation] [--fix-ruby-style-regex] [--allow-assertions] 
42
          [--encoding ENCODING] [-v ...] [-q]
43
```
44

45
### Required Arguments
46

47
```bash
48
-d FILE, --data-file FILE        # The file to be validated
49
-s FILE, --schema-file FILE      # Schema definition file (can be specified multiple times)
50
```
51

52
### Optional Arguments
53

54
```bash
55
-e FILE, --extension FILE        # Python extension file (can be specified multiple times)
56
-h, --help                       # Show help message and exit
57
-q, --quiet                      # Suppress terminal output
58
-v, --verbose                    # Verbose terminal output (multiple -v increases verbosity)
59
--version                        # Display version number and exit
60
```
61

62
### Validation Options
63

64
```bash
65
--strict-rule-validation         # Enable strict validation of all keywords for Rule objects
66
--fix-ruby-style-regex          # Fix Ruby-style regex compatibility issues  
67
--allow-assertions               # Enable assertion keyword (disabled by default for security)
68
--encoding ENCODING              # Specify encoding to open data and schema files
69
```
70

71
## Usage Examples
72

73
### Basic File Validation
74

75
```bash
76
# Validate a YAML file against a schema
77
pykwalify -d data.yaml -s schema.yaml
78

79
# Validate a JSON file against a schema
80
pykwalify -d data.json -s schema.yaml
81

82
# Multiple schema files
83
pykwalify -d data.yaml -s base_schema.yaml -s extended_schema.yaml
84
```
85

86
### Advanced Validation Options
87

88
```bash
89
# Strict validation with verbose output
90
pykwalify -d data.yaml -s schema.yaml --strict-rule-validation -vv
91

92
# With custom encoding
93
pykwalify -d data.yaml -s schema.yaml --encoding utf-16
94

95
# Enable assertions (use with caution)
96
pykwalify -d data.yaml -s schema.yaml --allow-assertions
97

98
# Fix Ruby regex compatibility
99
pykwalify -d data.yaml -s schema.yaml --fix-ruby-style-regex
100
```
101

102
### Using Extensions
103

104
```bash
105
# Load custom validation functions
106
pykwalify -d data.yaml -s schema.yaml -e custom_validators.py
107

108
# Multiple extension files
109
pykwalify -d data.yaml -s schema.yaml -e validators1.py -e validators2.py
110
```
111

112
### Output Control
113

114
```bash
115
# Quiet mode (suppress output)
116
pykwalify -d data.yaml -s schema.yaml -q
117

118
# Verbose output (single level)
119
pykwalify -d data.yaml -s schema.yaml -v
120

121
# Very verbose output (multiple levels)
122
pykwalify -d data.yaml -s schema.yaml -vvv
123
```
124

125
### Version and Help
126

127
```bash
128
# Show version
129
pykwalify --version
130

131
# Show help
132
pykwalify --help
133
pykwalify -h
134
```
135

136
## Exit Codes
137

138
The CLI uses specific exit codes to indicate different types of errors:
139

140
```python { .api }
141
# Exit codes
142
0  # Success - no errors
143
1  # Unknown error
144
2  # Schema error - validation failure
145
3  # Core error - processing error
146
4  # Rule error - rule processing error
147
5  # Schema conflict - conflicting schema definitions
148
6  # Not mapping error - expected dict but got different type
149
7  # Not sequence error - expected list but got different type
150
```
151

152
## Integration Examples
153

154
### Shell Script Integration
155

156
```bash
157
#!/bin/bash
158

159
DATA_FILE="config.yaml"
160
SCHEMA_FILE="config_schema.yaml"
161

162
echo "Validating $DATA_FILE against $SCHEMA_FILE..."
163

164
if pykwalify -d "$DATA_FILE" -s "$SCHEMA_FILE" -q; then
165
    echo "✓ Validation successful"
166
    exit 0
167
else
168
    echo "✗ Validation failed"
169
    exit 1
170
fi
171
```
172

173
### Makefile Integration
174

175
```makefile
176
validate:
177
	@echo "Validating configuration files..."
178
	@pykwalify -d config/app.yaml -s schemas/app_schema.yaml
179
	@pykwalify -d config/db.yaml -s schemas/db_schema.yaml
180
	@echo "All validations passed!"
181

182
validate-verbose:
183
	pykwalify -d config/app.yaml -s schemas/app_schema.yaml -vv
184
	pykwalify -d config/db.yaml -s schemas/db_schema.yaml -vv
185

186
.PHONY: validate validate-verbose
187
```
188

189
### CI/CD Pipeline Integration
190

191
```yaml
192
# GitHub Actions example
193
- name: Validate YAML files
194
  run: |
195
    pip install pykwalify
196
    pykwalify -d .github/workflows/ci.yml -s schemas/github_workflow_schema.yaml
197
    pykwalify -d config/production.yaml -s schemas/config_schema.yaml
198

199
# GitLab CI example
200
validate_configs:
201
  script:
202
    - pip install pykwalify
203
    - pykwalify -d config.yaml -s schema.yaml --strict-rule-validation
204
  only:
205
    changes:
206
      - "*.yaml"
207
      - "*.yml"
208
```
209

210
### Batch Validation Script
211

212
```bash
213
#!/bin/bash
214

215
# Validate multiple files with the same schema
216
SCHEMA="schemas/api_schema.yaml"
217
EXIT_CODE=0
218

219
for file in data/*.yaml; do
220
    echo "Validating $file..."
221
    if ! pykwalify -d "$file" -s "$SCHEMA" -q; then
222
        echo "❌ $file failed validation"
223
        EXIT_CODE=1
224
    else
225
        echo "✅ $file passed validation"
226
    fi
227
done
228

229
if [ $EXIT_CODE -eq 0 ]; then
230
    echo "All files validated successfully!"
231
else
232
    echo "Some files failed validation"
233
fi
234

235
exit $EXIT_CODE
236
```
237

238
### Error Handling in Scripts
239

240
```bash
241
#!/bin/bash
242

243
validate_file() {
244
    local data_file=$1
245
    local schema_file=$2
246
    
247
    # Capture both exit code and output
248
    local output
249
    output=$(pykwalify -d "$data_file" -s "$schema_file" 2>&1)
250
    local exit_code=$?
251
    
252
    case $exit_code in
253
        0)
254
            echo "✓ $data_file: Valid"
255
            return 0
256
            ;;
257
        2)
258
            echo "✗ $data_file: Schema validation failed"
259
            echo "  Details: $output"
260
            return 2
261
            ;;
262
        3)
263
            echo "✗ $data_file: Core processing error"
264
            echo "  Details: $output"
265
            return 3
266
            ;;
267
        *)
268
            echo "✗ $data_file: Unknown error (code: $exit_code)"
269
            echo "  Details: $output"
270
            return $exit_code
271
            ;;
272
    esac
273
}
274

275
# Usage
276
validate_file "user_data.yaml" "user_schema.yaml"
277
validation_result=$?
278

279
if [ $validation_result -eq 0 ]; then
280
    echo "Proceeding with deployment..."
281
else
282
    echo "Aborting deployment due to validation errors"
283
    exit $validation_result
284
fi
285
```
286

287
### Custom Extension Example
288

289
Create a custom validator file (`custom_validators.py`):
290

291
```python
292
# custom_validators.py
293
def validate_custom_id(value):
294
    """Custom validation function for special ID format."""
295
    if not isinstance(value, str):
296
        return False
297
    
298
    # Check if it matches pattern: PREFIX-YYYYMMDD-NNNN
299
    import re
300
    pattern = r'^[A-Z]{2,4}-\d{8}-\d{4}$'
301
    return bool(re.match(pattern, value))
302
```
303

304
Schema using the custom validator:
305

306
```yaml
307
# schema.yaml
308
type: map
309
mapping:
310
  id:
311
    type: str
312
    func: validate_custom_id
313
  name:
314
    type: str
315
    required: true
316
```
317

318
Command to use custom validator:
319

320
```bash
321
pykwalify -d data.yaml -s schema.yaml -e custom_validators.py
322
```
323

324
## Environment Variables
325

326
### Setting Encoding
327

328
```bash
329
# Force UTF-8 encoding for all operations
330
export PYTHONIOENCODING=UTF-8
331
pykwalify -d data.yaml -s schema.yaml
332
```
333

334
### Debug Mode
335

336
```bash
337
# Enable detailed debugging output
338
export PYKWALIFY_DEBUG=true
339
pykwalify -d data.yaml -s schema.yaml -vv
340
```
341

342
## Best Practices
343

344
### 1. Schema Organization
345

346
```bash
347
# Use organized schema directory structure
348
schemas/
349
├── common/
350
│   ├── base.yaml
351
│   └── types.yaml
352
├── api/
353
│   ├── request.yaml
354
│   └── response.yaml
355
└── config/
356
    ├── app.yaml
357
    └── database.yaml
358

359
# Validate with multiple schemas
360
pykwalify -d config.yaml -s schemas/common/base.yaml -s schemas/config/app.yaml
361
```
362

363
### 2. Automated Validation
364

365
```bash
366
# Pre-commit hook example
367
#!/bin/sh
368
# .git/hooks/pre-commit
369

370
echo "Running YAML validation..."
371
find . -name "*.yaml" -o -name "*.yml" | while read file; do
372
    if [[ $file == *"schema"* ]]; then
373
        continue  # Skip schema files
374
    fi
375
    
376
    schema_file="schemas/$(basename "$file" .yaml)_schema.yaml"
377
    if [ -f "$schema_file" ]; then
378
        pykwalify -d "$file" -s "$schema_file" -q || exit 1
379
    fi
380
done
381

382
echo "✓ All YAML files validated successfully"
383
```
384

385
### 3. Performance Optimization
386

387
```bash
388
# For large files, use appropriate verbosity
389
pykwalify -d large_file.yaml -s schema.yaml -q  # Fastest
390

391
# For debugging, use verbose output
392
pykwalify -d problem_file.yaml -s schema.yaml -vv  # Most detailed
393
```