credl-parser-evaluator
Version:
TypeScript-based CREDL Parser and Evaluator that processes CREDL files and outputs complete Intermediate Representations
1,172 lines (953 loc) • 41.1 kB
Markdown
# CREDL CLI Examples
Comprehensive examples and sample outputs for all CREDL CLI commands.
## Table of Contents
- [Overview](#overview)
- [Basic Usage Examples](#basic-usage-examples)
- [Command Examples](#command-examples)
- [credl run](#credl-run)
- [credl validate](#credl-validate)
- [credl convert](#credl-convert)
- [credl init](#credl-init)
- [credl test](#credl-test)
- [credl benchmark](#credl-benchmark)
- [Workflow Examples](#workflow-examples)
- [Troubleshooting Examples](#troubleshooting-examples)
## Overview
This document provides practical examples of using the CREDL CLI with real command outputs and sample files. Each example shows the exact command used and the expected output format.
## Basic Usage Examples
### Getting Help
```bash
# Display main help
$ credl --help
# Display help for specific command
$ credl run --help
$ credl validate --help
```
### Version Information
```bash
$ credl --version
1.0.0
```
## Command Examples
### credl run
Process and evaluate CREDL files to generate complete Intermediate Representation.
#### Basic Processing
```bash
$ credl run examples/01-minimal-office.credl
```
**Output (pretty format, default):**
```
┌─────────────────────────────────────────────────────────────┐
│ CREDL Processing Results │
├─────────────────────────────────────────────────────────────┤
│ File: examples/01-minimal-office.credl │
│ Status: ✅ Valid │
│ Processing Time: 43ms │
│ │
│ Summary: │
│ • Assets: 1 │
│ • Buildings: 1 │
│ • Spaces: 4 │
│ • Assumptions: 6 │
│ • Models: 1 │
│ │
│ Validation Results: │
│ • Errors: 0 │
│ • Warnings: 0 │
│ │
│ IR Generation: │
│ • Cross-references resolved: ✅ │
│ • Templates applied: ✅ │
│ • Presets resolved: ✅ │
└─────────────────────────────────────────────────────────────┘
```
#### JSON Output to File
```bash
$ credl run examples/01-minimal-office.credl --format json --output office-ir.json
```
**Output:**
```
✅ Processing completed successfully
📄 Results written to: office-ir.json
⏱️ Processing time: 43ms
```
#### Summary Format
```bash
$ credl run examples/01-minimal-office.credl --format summary
```
**Output:**
```
examples/01-minimal-office.credl: ✅ Valid (43ms) - Assets: 1, Spaces: 4, Assumptions: 6
```
#### Verbose Processing
```bash
$ credl run examples/01-minimal-office.credl --verbose
```
**Output:**
```
🔍 Loading file: examples/01-minimal-office.credl
📊 File size: 2.1 KB
⚙️ Parsing CREDL content...
✅ Parsing completed (8ms)
🔍 Validating structure...
✅ Schema validation passed
✅ Cross-reference validation passed
✅ Validation completed (12ms)
⚙️ Generating IR...
🔧 Resolving presets...
✅ Resolved 0 preset references
🔧 Resolving templates...
✅ Applied 0 templates
🔧 Processing assumptions...
✅ Processed 6 assumptions
🔧 Processing models...
✅ Processed 1 model
✅ IR generation completed (23ms)
┌─────────────────────────────────────────────────────────────┐
│ CREDL Processing Results │
├─────────────────────────────────────────────────────────────┤
│ File: examples/01-minimal-office.credl │
│ Status: ✅ Valid │
│ Processing Time: 43ms │
│ │
│ Summary: │
│ • Assets: 1 │
│ • Buildings: 1 │
│ • Spaces: 4 │
│ • Assumptions: 6 │
│ • Models: 1 │
│ │
│ Processing Details: │
│ • Parse time: 8ms │
│ • Validation time: 12ms │
│ • IR generation time: 23ms │
│ • Memory usage: 12.4 MB │
└─────────────────────────────────────────────────────────────┘
```
### credl validate
Validate CREDL files for syntax and specification compliance.
#### Single File Validation
```bash
$ credl validate examples/01-minimal-office.credl
```
**Output (table format, default):**
```
┌─────────────────────────────┬────────┬────────┬──────────┬─────────────────┐
│ File │ Status │ Errors │ Warnings │ Processing Time │
├─────────────────────────────┼────────┼────────┼──────────┼─────────────────┤
│ examples/01-minimal-office.credl │ ✅ │ 0 │ 0 │ 34ms │
└─────────────────────────────┴────────┴────────┴──────────┴─────────────────┘
Validation Summary:
✅ All files valid (1/1)
⏱️ Total time: 34ms
```
#### Multiple File Validation
```bash
$ credl validate examples/*.credl
```
**Output:**
```
┌─────────────────────────────────────┬────────┬────────┬──────────┬─────────────────┐
│ File │ Status │ Errors │ Warnings │ Processing Time │
├─────────────────────────────────────┼────────┼────────┼──────────┼─────────────────┤
│ examples/01-minimal-office.credl │ ✅ │ 0 │ 0 │ 34ms │
│ examples/02-comprehensive-mixed.credl│ ✅ │ 0 │ 2 │ 67ms │
│ examples/03-presets-templates.credl │ ✅ │ 0 │ 1 │ 45ms │
│ examples/04-extensions-scenarios.credl│ ✅ │ 0 │ 0 │ 52ms │
│ examples/05-industrial-portfolio.credl│ ✅ │ 0 │ 1 │ 78ms │
└─────────────────────────────────────┴────────┴────────┴──────────┴─────────────────┘
Validation Summary:
✅ All files valid (5/5)
⚠️ Total warnings: 4
⏱️ Average processing time: 55ms
⏱️ Total time: 276ms
```
#### Validation with Errors
```bash
$ credl validate src/test-temp-errors/invalid.credl
```
**Output:**
```
┌──────────────────────────────────┬────────┬────────┬──────────┬─────────────────┐
│ File │ Status │ Errors │ Warnings │ Processing Time │
├──────────────────────────────────┼────────┼────────┼──────────┼─────────────────┤
│ src/test-temp-errors/invalid.credl│ ❌ │ 3 │ 1 │ 28ms │
└──────────────────────────────────┴────────┴────────┴──────────┴─────────────────┘
❌ Validation Errors:
📄 src/test-temp-errors/invalid.credl:
❌ Error: Missing required field 'metadata.version'
❌ Error: Invalid property type 'InvalidType' in asset 'asset-1'
❌ Error: Cross-reference 'building-999' not found in spaces[0].parent_building
⚠️ Warning: Assumption 'unused_rate' is defined but never referenced
Validation Summary:
❌ 1 invalid file (0/1 valid)
🚫 Total errors: 3
⚠️ Total warnings: 1
⏱️ Total time: 28ms
Exit code: 1
```
#### JSON Format Validation
```bash
$ credl validate examples/*.credl --format json --output validation-report.json
```
**Output:**
```
✅ Validation completed
📄 Results written to: validation-report.json
📊 Summary: 5/5 files valid, 0 errors, 4 warnings
```
**JSON Output (validation-report.json):**
```json
{
"summary": {
"totalFiles": 5,
"validFiles": 5,
"invalidFiles": 0,
"totalErrors": 0,
"totalWarnings": 4,
"averageProcessingTime": 55,
"totalProcessingTime": 276
},
"results": [
{
"file": "examples/01-minimal-office.credl",
"isValid": true,
"errors": [],
"warnings": [],
"processingTime": 34
},
{
"file": "examples/02-comprehensive-mixed.credl",
"isValid": true,
"errors": [],
"warnings": [
"Assumption 'alternative_scenario' defined but not used in models",
"Space 'retail-common-1' has unusually high common area ratio"
],
"processingTime": 67
}
]
}
```
#### Summary Format
```bash
$ credl validate examples/*.credl --format summary
```
**Output:**
```
examples/01-minimal-office.credl: ✅ Valid (0 errors, 0 warnings)
examples/02-comprehensive-mixed.credl: ✅ Valid (0 errors, 2 warnings)
examples/03-presets-templates.credl: ✅ Valid (0 errors, 1 warning)
examples/04-extensions-scenarios.credl: ✅ Valid (0 errors, 0 warnings)
examples/05-industrial-portfolio.credl: ✅ Valid (0 errors, 1 warning)
Summary: 5/5 files valid (100%)
```
### credl convert
Convert CREDL files to Intermediate Representation (IR) format.
#### Basic Conversion
```bash
$ credl convert examples/01-minimal-office.credl
```
**Output (JSON format, default):**
```json
{
"metadata": {
"version": "0.2",
"name": "Downtown Office Building",
"description": "A simple office building in downtown Chicago",
"created_date": "2025-01-21",
"generated_at": "2025-01-21T15:30:45.123Z",
"generator": "CREDL Parser v1.0.0",
"generator_version": "1.0.0"
},
"assets": [
{
"id": "asset-1",
"name": "Downtown Office",
"property_type": "office",
"location": "Chicago, IL",
"total_area_sf": 50000
}
],
"buildings": [
{
"id": "building-1",
"name": "Main Building",
"parent_asset": "asset-1",
"floors": 10,
"total_area_sf": 50000,
"year_built": 2020
}
],
"spaces": [
{
"id": "suite-100",
"parent_building": "building-1",
"type": "office",
"area_sf": 12500,
"floor": 1,
"lease": {
"status": "leased",
"tenant": "Tech Corp",
"rent_psf": 45,
"lease_type": "gross"
}
}
],
"validation": {
"isValid": true,
"errors": [],
"warnings": []
}
}
```
#### Convert to File
```bash
$ credl convert examples/01-minimal-office.credl --output office-building-ir.json
```
**Output:**
```
✅ Conversion completed successfully
📄 IR written to: office-building-ir.json
📊 Generated IR with 1 asset, 1 building, 4 spaces
⏱️ Processing time: 38ms
```
#### Pretty Format
```bash
$ credl convert examples/01-minimal-office.credl --format pretty
```
**Output:**
```
CREDL Intermediate Representation
================================
Metadata:
Version: 0.2
Name: Downtown Office Building
Description: A simple office building in downtown Chicago
Created: 2025-01-21
Generated: 2025-01-21T15:30:45.123Z
Assets (1):
📍 asset-1: Downtown Office
Type: office
Location: Chicago, IL
Total Area: 50,000 sf
Buildings (1):
🏢 building-1: Main Building
Parent: asset-1
Floors: 10
Area: 50,000 sf
Built: 2020
Spaces (4):
🏠 suite-100: Office Space
Building: building-1
Type: office
Area: 12,500 sf
Status: ✅ Leased (Tech Corp)
Rent: $45/sf (gross)
🏠 suite-200: Office Space
Building: building-1
Type: office
Area: 12,500 sf
Status: 🟡 Vacant
🏠 suite-300: Office Space
Building: building-1
Type: office
Area: 12,500 sf
Status: ✅ Leased (Finance Co)
Rent: $42/sf (gross)
🏠 suite-400: Office Space
Building: building-1
Type: office
Area: 12,500 sf
Status: ✅ Leased (Law Firm)
Rent: $48/sf (gross)
Assumptions (6):
📊 discount_rate: 8.0% (fixed)
📊 rent_growth: 2.5% ± 1.0% (normal distribution)
📊 vacancy_rate: 5.0% (fixed)
📊 operating_expenses: $12.50/sf (fixed)
📊 cap_rate: 6.5% (fixed)
📊 exit_cap_rate: 7.0% (fixed)
Models (1):
🧮 base_dcf: Deterministic DCF
Duration: 10 years
Steps per year: 12
Inputs: 6 assumptions
Outputs: IRR, NPV
Validation Status: ✅ Valid (0 errors, 0 warnings)
```
#### Skip Validation for Speed
```bash
$ credl convert examples/05-industrial-portfolio.credl --skip-validation --format json
```
**Output:**
```
⚠️ Validation skipped - processing without validation
✅ Conversion completed successfully
📊 Generated IR with 3 assets, 5 buildings, 45 spaces
⏱️ Processing time: 89ms (validation saved ~25ms)
```
#### Convert with Verbose Output
```bash
$ credl convert examples/01-minimal-office.credl --verbose --format pretty
```
**Output:**
```
🔍 Loading file: examples/01-minimal-office.credl
📊 File size: 2.1 KB
⚙️ Parsing CREDL content...
✅ Parsing completed (8ms)
🔍 Validating structure...
✅ Schema validation passed
✅ Cross-reference validation passed
✅ Validation completed (12ms)
⚙️ Converting to IR...
🔧 Processing metadata...
✅ Metadata processed
🔧 Processing assets...
✅ 1 asset processed
🔧 Processing buildings...
✅ 1 building processed
🔧 Processing spaces...
✅ 4 spaces processed
🔧 Processing assumptions...
✅ 6 assumptions processed
🔧 Processing models...
✅ 1 model processed
🔧 Generating unique IDs...
✅ IDs generated
✅ IR conversion completed (18ms)
📄 IR Summary:
• Assets: 1
• Buildings: 1
• Spaces: 4
• Assumptions: 6
• Models: 1
• Total elements: 13
[... pretty format output continues ...]
```
### credl init
Initialize new CREDL projects with interactive prompts and templates.
#### Interactive Mode
```bash
$ credl init
```
**Output:**
```
🏗️ CREDL Project Initialization
? What type of property are you modeling? (Use arrow keys)
❯ Office
Retail
Mixed-Use
Industrial
Residential
? What is the name of your property? Downtown Office Tower
? Where is the property located? Seattle, WA
? Output file name: (downtown-office-tower.credl)
✅ Created downtown-office-tower.credl
📊 Generated content:
• 1 asset (Downtown Office Tower)
• 1 building (Main Building, 12 floors)
• 4 office spaces (48,000 total sf)
• 6 financial assumptions
• 1 DCF model with 10-year analysis
Next steps:
1. Validate: credl validate downtown-office-tower.credl
2. Process: credl run downtown-office-tower.credl
3. Convert: credl convert downtown-office-tower.credl --output ir.json
📄 Project initialized successfully!
```
#### Non-Interactive Office Building
```bash
$ credl init --type office --name "Corporate Headquarters" --location "Austin, TX"
```
**Output:**
```
🏗️ Creating Office project...
✅ Created corporate-headquarters.credl
📊 Generated office building template:
• Property: Corporate Headquarters (Austin, TX)
• Building: 8 floors, 75,000 sf
• Spaces: 6 office suites
• Assumptions: Rent ($38/sf), Growth (2.5%), Vacancy (7%)
• Model: 10-year DCF analysis
⏱️ Generation time: 15ms
📄 Ready for validation and processing!
```
#### Retail Center Template
```bash
$ credl init --type retail --name "Village Shopping Center" --location "Denver, CO" --output retail-center.credl
```
**Output:**
```
🏗️ Creating Retail project...
✅ Created retail-center.credl
📊 Generated retail center template:
• Property: Village Shopping Center (Denver, CO)
• Building: Single story, 45,000 sf
• Spaces: 2 anchor tenants + 8 inline shops + common areas
• Assumptions: Base rent + percentage rent, CAM charges
• Model: Retail cash flow with tenant improvements
⏱️ Generation time: 18ms
📄 Ready for validation and processing!
```
#### Mixed-Use Development
```bash
$ credl init --type mixed-use --name "Urban Plaza" --location "Portland, OR" --verbose
```
**Output:**
```
🏗️ Creating Mixed-Use project...
🔧 Generating mixed-use template:
📍 Location: Portland, OR
🏢 Property type: Mixed-Use
📋 Template: mixed_use_standard
✅ Template generation:
🏢 Building 1: Office Tower (15 floors, 120,000 sf)
🏢 Building 2: Retail Podium (2 floors, 25,000 sf)
🏠 Residential: 50 apartment units (Building 1, floors 3-15)
🏪 Retail: Ground floor + mezzanine (restaurants, shops)
🏢 Office: Floors 16-30 (corporate tenants)
📊 Generated assumptions:
• Office rent: $42/sf (gross)
• Retail rent: $55/sf + 6% of sales
• Residential rent: $2,850/month average
• Mixed-use operating expenses: $15.50/sf
• Development-specific cap rates and growth assumptions
🧮 Created sophisticated cash flow model:
• 15-year analysis period
• Monthly cash flow calculations
• Tenant improvement reserves
• Mixed-use financing structure
• Scenario analysis capabilities
✅ Created urban-plaza.credl
⏱️ Generation time: 24ms
📄 Ready for validation and processing!
```
#### Force Overwrite Existing File
```bash
$ credl init --type industrial --name "Distribution Center" --force
```
**Output:**
```
⚠️ File 'distribution-center.credl' already exists
🔧 Force flag enabled - overwriting existing file
✅ Created distribution-center.credl
📊 Generated industrial template:
• Property: Distribution Center
• Building: Warehouse (250,000 sf) + Office (15,000 sf)
• Spaces: Loading docks, storage areas, office suites
• Assumptions: Triple-net lease structure
• Model: Industrial cash flow with development phases
📄 Existing file overwritten successfully!
```
### credl test
Run CREDL tests and validation (developer command).
#### Run All Tests
```bash
$ credl test
```
**Output:**
```
🧪 Running CREDL Test Suite
📚 Discovering test files...
✅ Found 25 test files (287 tests)
🚀 Running tests...
PASS src/parser/CREDLParser.test.ts (4.2s)
PASS src/engine/IRBuilder.test.ts (3.8s)
PASS src/api/index.test.ts (2.1s)
PASS examples/examples.test.ts (5.3s)
PASS src/performance/performance.test.ts (8.7s)
Test Suites: 25 passed, 25 total
Tests: 287 passed, 287 total
Snapshots: 0 total
Time: 24.156s
✅ All tests passed!
```
#### Run Specific Test File
```bash
$ credl test --single src/parser/CREDLParser.test.ts
```
**Output:**
```
🧪 Running Single Test File
📄 Test file: src/parser/CREDLParser.test.ts
PASS src/parser/CREDLParser.test.ts
CREDLParser
✓ should parse valid CREDL files (23ms)
✓ should handle metadata correctly (15ms)
✓ should validate required fields (18ms)
✓ should parse complex asset structures (34ms)
✓ should handle all property types (28ms)
✓ should reject invalid YAML (12ms)
Test Suites: 1 passed, 1 total
Tests: 6 passed, 6 total
Time: 4.234s
✅ Parser tests passed!
```
#### Test with Coverage
```bash
$ credl test --coverage
```
**Output:**
```
🧪 Running Tests with Coverage
📊 Generating coverage report...
PASS src/parser/CREDLParser.test.ts
PASS src/engine/IRBuilder.test.ts
[... all test files ...]
Test Suites: 25 passed, 25 total
Tests: 287 passed, 287 total
Time: 26.891s
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------------------|---------|----------|---------|---------|------------------
All files | 91.25 | 89.47 | 94.12 | 91.03 |
src/api | 95.83 | 92.31 | 100.00 | 95.65 | 45,67,89
src/parser | 93.75 | 88.89 | 96.15 | 93.48 |
src/engine | 89.47 | 86.67 | 91.18 | 89.29 |
src/cli | 87.23 | 84.21 | 89.47 | 87.50 |
✅ Coverage: 91.25% statements, target met!
📄 Coverage report: coverage/lcov-report/index.html
```
### credl benchmark
Run performance benchmarks on CREDL files and processing.
#### Standard Benchmark Suite
```bash
$ credl benchmark
```
**Output:**
```
🏁 CREDL Performance Benchmark
📊 Running Standard Suite (5 tests, 10 iterations, 3 warmup)
⚡ Warming up... (3 iterations)
✅ Warmup completed
🚀 Running benchmarks...
┌─────────────────────────────────────────────────────────────────────────────┐
│ CREDL Benchmark Results │
├─────────────────────────────────────────────────────────────────────────────┤
│ Suite: standard │ Date: 2025-01-21 15:45 │
│ Iterations: 10 │ Warmup: 3 │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────┬─────────┬─────────┬─────────┬─────────┬─────────────┐
│ Test │ Min │ Max │ Mean │ Std Dev │ Rating │
├──────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────────┤
│ Parse 10 spaces │ 18ms │ 28ms │ 23ms │ 3.2ms │ Excellent │
│ Parse 25 spaces │ 31ms │ 47ms │ 38ms │ 5.1ms │ Excellent │
│ Parse 50 spaces │ 67ms │ 89ms │ 78ms │ 7.8ms │ Good │
│ Parse 75 spaces │ 98ms │ 125ms │ 112ms │ 12.3ms │ Good │
│ Parse 100 spaces │ 134ms │ 167ms │ 149ms │ 15.7ms │ Good │
└──────────────────────┴─────────┴─────────┴─────────┴─────────┴─────────────┘
Performance Summary:
• Average processing speed: ~1.5ms per space
• Performance rating: Good (meets requirements)
• Scaling efficiency: Linear (expected)
• Memory usage: Within normal limits
✅ All benchmarks completed successfully!
⏱️ Total benchmark time: 2m 34s
```
#### Benchmark Specific File with Memory Analysis
```bash
$ credl benchmark --file examples/05-industrial-portfolio.credl --memory --iterations 20
```
**Output:**
```
🏁 Custom File Benchmark
📄 File: examples/05-industrial-portfolio.credl
📊 Content: 3 assets, 5 buildings, 45 spaces, 12 assumptions
🔄 Iterations: 20 (5 warmup)
⚡ Warming up... (5 iterations)
✅ Warmup completed
🚀 Running performance analysis...
Performance Results:
┌─────────────────────┬─────────┬─────────┬─────────┬─────────┬─────────────┐
│ Metric │ Min │ Max │ Mean │ Std Dev │ P95/P99 │
├─────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────────┤
│ Processing Time │ 187ms │ 234ms │ 208ms │ 14.2ms │ 228/232ms │
│ Parse Time │ 45ms │ 67ms │ 56ms │ 6.8ms │ 65/66ms │
│ Validation Time │ 78ms │ 98ms │ 87ms │ 7.1ms │ 96/97ms │
│ IR Generation Time │ 64ms │ 89ms │ 75ms │ 8.9ms │ 86/88ms │
└─────────────────────┴─────────┴─────────┴─────────┴─────────┴─────────────┘
Memory Analysis:
┌─────────────────────┬─────────┬─────────┬─────────┬─────────────────────────┐
│ Memory Metric │ Min │ Max │ Mean │ Details │
├─────────────────────┼─────────┼─────────┼─────────┼─────────────────────────┤
│ Heap Used │ 28.3MB │ 34.7MB │ 31.2MB │ ~0.69MB per space │
│ Heap Total │ 45.1MB │ 52.8MB │ 48.9MB │ Good allocation pattern │
│ RSS │ 67.2MB │ 78.5MB │ 72.4MB │ Within expected range │
└─────────────────────┴─────────┴─────────┴─────────┴─────────────────────────┘
Efficiency Analysis:
• Processing speed: ~4.6ms per space (Good)
• Memory efficiency: ~0.69MB per space (Excellent)
• Scaling trend: Linear (as expected)
• Performance rating: Good
✅ Benchmark completed successfully!
⏱️ Total time: 1m 47s
```
## Workflow Examples
Real-world workflows combining multiple CLI commands for complete CREDL development.
### Complete Development Workflow
#### 1. New Project Development
```bash
# Initialize new office project
$ credl init --type office --name "Tech Campus" --location "San Francisco, CA"
🏗️ Creating Office project...
✅ Created tech-campus.credl
# Validate the generated project
$ credl validate tech-campus.credl --verbose
🔍 Validating tech-campus.credl...
✅ Schema validation passed
✅ Cross-reference validation passed
✅ All assumptions properly defined
✅ Model configuration valid
# Process the project to see results
$ credl run tech-campus.credl --format pretty
┌─────────────────────────────────────────────────────────────┐
│ CREDL Processing Results │
├─────────────────────────────────────────────────────────────┤
│ File: tech-campus.credl │
│ Status: ✅ Valid │
│ Processing Time: 52ms │
│ │
│ Summary: Tech Campus (San Francisco, CA) │
│ • Assets: 1 │
│ • Buildings: 1 (8 floors, 85,000 sf) │
│ • Spaces: 6 office suites │
│ • Assumptions: 6 (rent: $65/sf, growth: 3.5%) │
│ • Models: 1 (10-year DCF) │
└─────────────────────────────────────────────────────────────┘
# Convert to IR for further analysis
$ credl convert tech-campus.credl --output tech-campus-ir.json --format json
✅ Conversion completed successfully
📄 IR written to: tech-campus-ir.json
```
#### 2. CI/CD Pipeline Workflow
```bash
# Validate all CREDL files in repository
$ credl validate **/*.credl --format json --output validation-report.json
✅ Validation completed
📊 Summary: 12/12 files valid, 0 errors, 3 warnings
📄 Results written to: validation-report.json
# Run comprehensive tests
$ credl test --ci --coverage --max-workers 4
🧪 Running CREDL Test Suite (CI Mode)
✅ All 287 tests passed
📊 Coverage: 91.25% (target: 90%)
📄 Coverage report: coverage/lcov-report/index.html
# Performance validation with thresholds
$ credl benchmark --suite standard --threshold 500 --format json --output benchmark-report.json
🏁 CREDL Performance Benchmark
✅ All benchmarks within threshold (500ms)
📊 Average: 149ms (70% under threshold)
📄 Results written to: benchmark-report.json
# Exit codes: 0 = success, ready for deployment
```
#### 3. Multi-Property Portfolio Analysis
```bash
# Create multiple property projects
$ credl init --type office --name "Office Tower A" --location "NYC" --output tower-a.credl
$ credl init --type retail --name "Shopping Center B" --location "LA" --output center-b.credl
$ credl init --type mixed-use --name "Mixed Use C" --location "Chicago" --output mixed-c.credl
# Batch validation
$ credl validate tower-a.credl center-b.credl mixed-c.credl --format table
┌─────────────────┬────────┬────────┬──────────┬─────────────────┐
│ File │ Status │ Errors │ Warnings │ Processing Time │
├─────────────────┼────────┼────────┼──────────┼─────────────────┤
│ tower-a.credl │ ✅ │ 0 │ 0 │ 34ms │
│ center-b.credl │ ✅ │ 0 │ 1 │ 28ms │
│ mixed-c.credl │ ✅ │ 0 │ 2 │ 45ms │
└─────────────────┴────────┴────────┴──────────┴─────────────────┘
# Process all properties for analysis
$ for file in *.credl; do
echo "Processing $file..."
credl convert "$file" --output "${file%.credl}-ir.json" --format json
done
Processing tower-a.credl...
✅ IR written to: tower-a-ir.json
Processing center-b.credl...
✅ IR written to: center-b-ir.json
Processing mixed-c.credl...
✅ IR written to: mixed-c-ir.json
# Portfolio performance analysis
$ credl benchmark --file tower-a.credl --file center-b.credl --file mixed-c.credl --format csv --output portfolio-performance.csv
🏁 Portfolio Benchmark Analysis
📊 3 properties analyzed
📄 Results written to: portfolio-performance.csv
```
### Development and Testing Workflow
#### 1. Iterative Development
```bash
# Start with template
$ credl init --type mixed-use --name "Development Project"
# Development loop
while [ $? -eq 0 ]; do
# Edit the CREDL file with your preferred editor
nano development-project.credl
# Quick validation check
credl validate development-project.credl --format summary
# If valid, test processing
if [ $? -eq 0 ]; then
credl run development-project.credl --format summary --quiet
echo "✅ Iteration successful"
else
echo "❌ Validation failed, check errors above"
fi
# Ask to continue
read -p "Continue development? (y/n): " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
break
fi
done
```
#### 2. Performance Optimization Workflow
```bash
# Baseline performance measurement
$ credl benchmark --file large-property.credl --iterations 20 --memory --output baseline.json
🏁 Baseline Performance Measurement
📊 Mean processing time: 234ms
📊 Memory usage: 45.2MB
# After making optimizations, compare performance
$ credl benchmark --file large-property.credl --iterations 20 --memory --compare baseline.json
🏁 Performance Comparison
📊 Current: 198ms (15.4% improvement ✅)
📊 Memory: 38.7MB (14.4% reduction ✅)
📈 Performance improved significantly!
# Detailed profiling for further optimization
$ credl benchmark --file large-property.credl --profile --verbose
🔍 Detailed Performance Profile:
• Parse time: 42ms (21%)
• Validation time: 67ms (34%)
• IR generation: 89ms (45%)
🎯 Focus optimization on IR generation phase
```
### Error Handling and Debugging Workflows
#### 1. Troubleshooting Invalid Files
```bash
# Attempt to process problematic file
$ credl run problematic-property.credl
❌ Processing failed with validation errors
# Get detailed validation information
$ credl validate problematic-property.credl --verbose --format table
┌──────────────────────────────┬────────┬────────┬──────────┬─────────────────┐
│ File │ Status │ Errors │ Warnings │ Processing Time │
├──────────────────────────────┼────────┼────────┼──────────┼─────────────────┤
│ problematic-property.credl │ ❌ │ 4 │ 2 │ 23ms │
└──────────────────────────────┴────────┴────────┴──────────┴─────────────────┘
❌ Validation Errors:
Line 15: Missing required field 'metadata.version'
Line 23: Invalid property type 'InvalidType' in asset 'asset-1'
Line 45: Cross-reference 'building-999' not found
Line 67: Assumption 'invalid_rate' has invalid distribution type
⚠️ Validation Warnings:
Line 34: Assumption 'unused_assumption' defined but never used
Line 78: Large space area (>50,000 sf) may need verification
# Fix issues and re-validate
$ nano problematic-property.credl # Fix the issues
$ credl validate problematic-property.credl
✅ Validation passed! All errors resolved.
# Now process successfully
$ credl run problematic-property.credl --format summary
problematic-property.credl: ✅ Valid (67ms) - Assets: 1, Spaces: 12, Assumptions: 8
```
#### 2. Performance Investigation Workflow
```bash
# Identify slow-processing file
$ credl benchmark --file slow-property.credl --threshold 200
🏁 Performance Analysis
❌ Threshold exceeded: 347ms > 200ms
🔍 Investigation needed
# Detailed analysis with profiling
$ credl benchmark --file slow-property.credl --profile --memory --verbose
Performance Breakdown:
┌─────────────────────┬─────────┬─────────────────────────────────┐
│ Phase │ Time │ Details │
├─────────────────────┼─────────┼─────────────────────────────────┤
│ File Reading │ 3ms │ Normal │
│ YAML Parsing │ 23ms │ Normal │
│ Schema Validation │ 45ms │ Normal │
│ Cross-ref Resolution│ 156ms │ ⚠️ Slow (many references) │
│ Template Processing │ 89ms │ ⚠️ Slow (complex templates) │
│ IR Generation │ 31ms │ Normal │
└─────────────────────┴─────────┴─────────────────────────────────┘
🎯 Optimization targets:
1. Reduce cross-reference complexity
2. Simplify template structures
3. Consider breaking into smaller files
# Test with validation disabled for comparison
$ credl convert slow-property.credl --skip-validation --format json | wc -c > /dev/null
$ echo "Conversion without validation: faster processing confirmed"
⏱️ Processing time without validation: 89ms (74% faster)
💡 Consider --skip-validation for production processing if validation done separately
```
## Troubleshooting Examples
Common CLI issues, error scenarios, and their solutions.
### Installation Issues
#### Command Not Found
```bash
$ credl --version
-bash: credl: command not found
```
**Solution:**
```bash
# Install globally
$ npm install -g credl-parser-evaluator
# Or use npx
$ npx credl-parser-evaluator --version
```
#### Permission Errors
```bash
$ npm install -g credl-parser-evaluator
npm ERR! Error: EACCES: permission denied
```
**Solution:**
```bash
# Configure npm prefix (recommended)
$ mkdir ~/.npm-global
$ npm config set prefix '~/.npm-global'
$ echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
$ source ~/.bashrc
$ npm install -g credl-parser-evaluator
```
### File Processing Errors
#### File Not Found
```bash
$ credl run missing-file.credl
❌ Error: File not found: missing-file.credl
```
#### Invalid YAML Syntax
```bash
$ credl run broken.credl
❌ Error: YAML parsing failed
Line: 23, Column: 5
Message: Unexpected character ':'
```
#### Validation Errors
```bash
$ credl validate invalid.credl
❌ Error: Missing required field 'metadata.version'
❌ Error: Invalid property type 'warehouse'
❌ Error: Cross-reference 'building-999' not found
```
### Performance Issues
#### Memory Errors
```bash
$ credl run huge-file.credl
FATAL ERROR: JavaScript heap out of memory
```
**Solution:**
```bash
$ export NODE_OPTIONS="--max-old-space-size=4096"
$ credl run huge-file.credl
```
#### Slow Processing
```bash
$ credl benchmark --threshold 100 --file slow.credl
❌ Threshold exceeded: 347ms > 100ms
```
**Solution:**
```bash
$ credl convert slow.credl --skip-validation
⏱️ Processing: 89ms (74% faster)
```
**CREDL CLI Examples** - Complete examples and troubleshooting for all CLI commands.