credl-parser-evaluator/docs/CLI_REFERENCE.md

TypeScript-based CREDL Parser and Evaluator that processes CREDL files and outputs complete Intermediate Representations

# CREDL CLI Reference

A comprehensive reference guide for the CREDL Command Line Interface (CLI) tool.

## Table of Contents

- [Overview](#overview)
- [Installation](#installation)
- [Global Options](#global-options)
- [Commands](#commands)
  - [credl run](#credl-run)
  - [credl validate](#credl-validate)
  - [credl convert](#credl-convert)
  - [credl init](#credl-init)
  - [credl test](#credl-test)
  - [credl benchmark](#credl-benchmark)
- [Output Formats](#output-formats)
- [Exit Codes](#exit-codes)
- [Environment Variables](#environment-variables)
- [Configuration Files](#configuration-files)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)

## Overview

The CREDL CLI provides a comprehensive command-line interface for working with CREDL (Commercial Real Estate Domain Language) files. It offers six main commands for different aspects of CREDL development and analysis:

1. **`credl run`** - Process and evaluate CREDL files
2. **`credl validate`** - Validate CREDL files for compliance
3. **`credl convert`** - Convert CREDL files to IR format
4. **`credl init`** - Initialize new CREDL projects
5. **`credl test`** - Run tests and validation (developer command)
6. **`credl benchmark`** - Performance benchmarking and analysis

## Installation

### Global Installation
```bash
npm install -g credl-parser-evaluator
```

### Local Usage (No Installation Required)
```bash
npx credl-parser-evaluator <command> [options]
```

### Verify Installation
```bash
credl --version
credl --help
```

## Global Options

The following options are available for all commands:

| Option | Description |
|--------|-------------|
| `--version` | Show version number |
| `--help` | Show help information |

## Commands

### credl run

Process and evaluate a CREDL file to generate complete Intermediate Representation (IR).

#### Usage
```bash
credl run <file> [options]
```

#### Arguments
| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `file` | string | Yes | Path to the CREDL file to process |

#### Options
| Option | Alias | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--output` | `-o` | string | console | Output file path |
| `--format` | `-f` | string | pretty | Output format: json, pretty, summary |
| `--verbose` | `-v` | boolean | false | Verbose output with processing details |
| `--quiet` | `-q` | boolean | false | Suppress output except errors |
| `--fail-fast` | | boolean | false | Stop on first validation error |
| `--include-metadata` | | boolean | true | Include processing metadata |
| `--resolve-presets` | | boolean | true | Resolve preset references |
| `--resolve-templates` | | boolean | true | Resolve template definitions |
| `--validate-references` | | boolean | true | Validate cross-references |

#### Examples
```bash
# Basic usage
credl run my-property.credl

# With JSON output to file
credl run my-property.credl --output result.json --format json

# Verbose processing with summary
credl run my-property.credl --format summary --verbose

# Fast processing (skip validation)
credl run my-property.credl --resolve-presets false --validate-references false
```

#### Output Formats

**pretty** (default):
```
┌─────────────────────────────────────────────────────────────┐
│                     CREDL Processing Results                 │
├─────────────────────────────────────────────────────────────┤
│ File: my-property.credl                                     │
│ Status: ✅ Valid                                             │
│ Processing Time: 45ms                                       │
│                                                             │
│ Summary:                                                    │
│   • Assets: 1                                              │
│   • Buildings: 1                                           │
│   • Spaces: 25                                             │
│   • Assumptions: 8                                         │
│   • Models: 1                                              │
└─────────────────────────────────────────────────────────────┘
```

**json**:
```json
{
  "metadata": {...},
  "assets": [...],
  "spaces": [...],
  "assumptions": [...],
  "models": [...],
  "validation": {
    "isValid": true,
    "errors": [],
    "warnings": []
  },
  "processingStats": {
    "processingTime": 45,
    "memoryUsage": 12.5
  }
}
```

**summary**:
```
my-property.credl: ✅ Valid (45ms) - Assets: 1, Spaces: 25, Assumptions: 8
```

#### Exit Codes
- `0` - Success
- `1` - Validation errors
- `2` - File not found
- `3` - Processing errors

---

### credl validate

Validate CREDL files for syntax and specification compliance.

#### Usage
```bash
credl validate <files...> [options]
```

#### Arguments
| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `files` | string[] | Yes | One or more CREDL files to validate (supports glob patterns) |

#### Options
| Option | Alias | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--output` | `-o` | string | console | Output validation results to file |
| `--format` | `-f` | string | table | Output format: table, json, summary |
| `--verbose` | `-v` | boolean | false | Verbose validation output |
| `--quiet` | `-q` | boolean | false | Suppress output except errors |
| `--fail-fast` | | boolean | false | Stop validation on first error per file |
| `--strict` | | boolean | false | Enable strict validation mode |
| `--check-references` | | boolean | true | Enable cross-reference validation |
| `--exit-code` | | boolean | true | Exit with non-zero code if files are invalid |

#### Examples
```bash
# Validate single file
credl validate my-property.credl

# Validate multiple files
credl validate *.credl properties/*.yaml

# Validate with JSON output
credl validate my-property.credl --format json --output validation-report.json

# Strict validation with verbose output
credl validate my-property.credl --strict --verbose

# Validate without cross-reference checking
credl validate my-property.credl --check-references false
```

#### Output Formats

**table** (default):
```
┌─────────────────────┬────────┬────────┬─────────────┬──────────────────────┐
│ File                │ Status │ Errors │ Warnings    │ Processing Time      │
├─────────────────────┼────────┼────────┼─────────────┼──────────────────────┤
│ my-property.credl   │   ✅   │   0    │      2      │        34ms          │
│ large-property.credl│   ❌   │   3    │      1      │        67ms          │
│ office-tower.credl  │   ✅   │   0    │      0      │        28ms          │
└─────────────────────┴────────┴────────┴─────────────┴──────────────────────┘

Validation Summary:
• Total Files: 3
• Valid Files: 2 (66.7%)
• Invalid Files: 1 (33.3%)
• Total Errors: 3
• Total Warnings: 3
• Average Processing Time: 43ms
```

**json**:
```json
{
  "summary": {
    "totalFiles": 3,
    "validFiles": 2,
    "invalidFiles": 1,
    "totalErrors": 3,
    "totalWarnings": 3,
    "averageProcessingTime": 43
  },
  "results": [
    {
      "file": "my-property.credl",
      "isValid": true,
      "errors": [],
      "warnings": [...],
      "processingTime": 34
    }
  ]
}
```

**summary**:
```
my-property.credl: ✅ Valid (0 errors, 2 warnings)
large-property.credl: ❌ Invalid (3 errors, 1 warning)
office-tower.credl: ✅ Valid (0 errors, 0 warnings)

Summary: 2/3 files valid (66.7%)
```

#### Exit Codes
- `0` - All files valid
- `1` - One or more files invalid
- `2` - File not found
- `3` - Processing errors

---

### credl convert

Convert CREDL files to Intermediate Representation (IR) format.

#### Usage
```bash
credl convert <file> [options]
```

#### Arguments
| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `file` | string | Yes | Path to the CREDL file to convert |

#### Options
| Option | Alias | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--output` | `-o` | string | console | Output file path |
| `--format` | `-f` | string | json | Output format: json, pretty |
| `--verbose` | `-v` | boolean | false | Verbose conversion output |
| `--quiet` | `-q` | boolean | false | Suppress output except errors |
| `--skip-validation` | | boolean | false | Skip validation for faster processing |
| `--include-metadata` | | boolean | true | Include processing metadata |
| `--resolve-presets` | | boolean | true | Resolve preset references |
| `--resolve-templates` | | boolean | true | Resolve template definitions |
| `--validate-references` | | boolean | true | Validate cross-references |
| `--generate-ids` | | boolean | true | Generate unique IDs for elements |

#### Examples
```bash
# Basic conversion
credl convert my-property.credl

# Convert to file with specific format
credl convert my-property.credl --output ir-output.json --format json

# Fast conversion (skip validation)
credl convert my-property.credl --skip-validation --format pretty

# Minimal conversion (no metadata)
credl convert my-property.credl --include-metadata false --generate-ids false
```

#### Output Formats

**json** (default):
```json
{
  "metadata": {
    "version": "0.2",
    "name": "Office Building",
    "generatedAt": "2025-01-21T10:30:00Z",
    "processingOptions": {...}
  },
  "assets": [...],
  "buildings": [...],
  "spaces": [...],
  "assumptions": [...],
  "models": [...],
  "validation": {...}
}
```

**pretty**:
```
CREDL Intermediate Representation
================================

Metadata:
  Version: 0.2
  Name: Office Building
  Generated: 2025-01-21T10:30:00Z

Assets: 1
  - ID: asset-1, Type: Office, Location: Chicago, IL

Buildings: 1
  - ID: building-1, Floors: 10, Area: 50,000 sf

Spaces: 25
  - ID: suite-100, Type: office, Area: 2,000 sf, Status: leased
  - ID: suite-101, Type: office, Area: 2,000 sf, Status: vacant
  ...

Assumptions: 8
  - discount_rate: 0.08 (fixed)
  - rent_growth: normal(0.025, 0.01) (distribution)
  ...
```

#### Exit Codes
- `0` - Conversion successful
- `1` - Validation errors (if validation enabled)
- `2` - File not found
- `3` - Conversion errors

---

### credl init

Initialize a new CREDL project with interactive prompts and templates.

#### Usage
```bash
credl init [options]
```

#### Options
| Option | Alias | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--type` | `-t` | string | - | Property type: office, retail, mixed-use, industrial, residential |
| `--name` | `-n` | string | - | Project name (skip interactive prompt) |
| `--location` | `-l` | string | - | Property location (skip interactive prompt) |
| `--output` | `-o` | string | {name}.credl | Output file path |
| `--force` | `-f` | boolean | false | Overwrite existing files without confirmation |
| `--verbose` | `-v` | boolean | false | Verbose output with detailed information |
| `--quiet` | `-q` | boolean | false | Suppress output except errors |

#### Examples
```bash
# Interactive mode
credl init

# Non-interactive with options
credl init --type office --name "Downtown Tower" --location "Chicago, IL"

# Specify output file
credl init --type retail --name "Shopping Center" --output retail-center.credl

# Force overwrite existing files
credl init --type mixed-use --name "Mixed Use" --force
```

#### Interactive Mode
```
? 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? Chicago, IL

? Output file name: (downtown-office-tower.credl)

✅ Created downtown-office-tower.credl
✅ Generated 1 asset, 1 building, 4 spaces
✅ Included 6 standard assumptions
✅ Created basic DCF model

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
```

#### Property Type Templates

**Office**:
- Standard office building with multiple floors
- Office spaces with standard lease terms
- Common area assumptions
- Operating expense assumptions
- Basic DCF model

**Retail**:
- Retail center with multiple tenants
- Anchor and inline tenant spaces
- Percentage rent assumptions
- CAM charges and recoveries
- Retail-specific cash flow model

**Mixed-Use**:
- Combined office and retail spaces
- Residential units (if applicable)
- Mixed-use specific assumptions
- Complex cash flow model

**Industrial**:
- Warehouse and distribution spaces
- Industrial tenant assumptions
- Triple-net lease structures
- Industrial-specific models

**Residential**:
- Apartment units or condominiums
- Residential rent assumptions
- Residential operating expenses
- Residential cash flow model

#### Exit Codes
- `0` - Project created successfully
- `1` - File already exists (without --force)
- `2` - Invalid property type
- `3` - File creation errors

---

### credl test

Run CREDL tests and validation (developer command).

#### Usage
```bash
credl test [options]
```

#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--single` | string | - | Run a specific test file |
| `--watch` | boolean | false | Watch mode for continuous testing |
| `--coverage` | boolean | false | Generate test coverage report |
| `--ci` | boolean | false | CI mode with appropriate settings |
| `--performance` | boolean | false | Include performance tests |
| `--examples` | boolean | false | Include example file tests |
| `--pattern` | string | **/*.test.ts | Test file pattern |
| `--max-workers` | number | - | Maximum number of worker processes |
| `--timeout` | number | 30000 | Test timeout in milliseconds |
| `--verbose` | `-v` | boolean | false | Verbose test output |
| `--quiet` | `-q` | boolean | false | Suppress output except errors |

#### Examples
```bash
# Run all tests
credl test

# Run specific test file
credl test --single src/parser/CREDLParser.test.ts

# Run with coverage
credl test --coverage

# Watch mode for development
credl test --watch --examples

# CI mode
credl test --ci --max-workers 4 --coverage

# Performance tests only
credl test --performance --timeout 60000
```

#### Test Categories

**Unit Tests**:
- Parser tests
- IR Builder tests
- Validation tests
- Engine tests

**Integration Tests**:
- End-to-end workflow tests
- CLI command tests
- File processing tests

**Performance Tests**:
- Benchmark tests
- Memory usage tests
- Large file tests

**Example Tests**:
- Example file validation
- Template tests
- Real-world scenario tests

#### Output
```
PASS src/parser/CREDLParser.test.ts
PASS src/engine/IRBuilder.test.ts
PASS src/cli/commands/run.test.ts
PASS examples/examples.test.ts

Test Suites: 25 passed, 25 total
Tests:       287 passed, 287 total
Snapshots:   0 total
Time:        15.234s
Ran all test suites.

Coverage:
┌─────────────────────┬────────┬────────┬────────┬────────┬─────────────────┐
│ File                │ % Stmts│ % Branch│ % Funcs│ % Lines│ Uncovered Lines │
├─────────────────────┼────────┼────────┼────────┼────────┼─────────────────┤
│ All files           │  91.25 │  89.47 │  94.12 │  91.03 │                 │
└─────────────────────┴────────┴────────┴────────┴────────┴─────────────────┘
```

#### Exit Codes
- `0` - All tests passed
- `1` - Some tests failed
- `2` - Test configuration errors
- `3` - Test execution errors

---

### credl benchmark

Run performance benchmarks on CREDL files and processing.

#### Usage
```bash
credl benchmark [options]
```

#### Options
| Option | Alias | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--file` | `-f` | string | - | Benchmark a specific CREDL file |
| `--output` | `-o` | string | console | Output benchmark results to file |
| `--format` | | string | table | Output format: table, json, csv |
| `--iterations` | `-i` | number | 10 | Number of benchmark iterations |
| `--warmup` | `-w` | number | 3 | Number of warmup iterations |
| `--verbose` | `-v` | boolean | false | Verbose benchmark output |
| `--quiet` | `-q` | boolean | false | Suppress output except results |
| `--compare` | `-c` | string | - | Compare with previous benchmark results |
| `--history` | | boolean | false | Save results to benchmark history |
| `--suite` | `-s` | string | standard | Run predefined suite: quick, standard, comprehensive |
| `--threshold` | `-t` | number | - | Performance threshold in milliseconds |
| `--memory` | | boolean | false | Include memory usage analysis |
| `--concurrent` | | number | - | Run concurrent benchmark tests |
| `--profile` | | boolean | false | Enable detailed profiling |

#### Examples
```bash
# Run standard benchmark suite
credl benchmark

# Benchmark specific file
credl benchmark --file large-property.credl --memory --iterations 20

# Comprehensive benchmarks with history
credl benchmark --suite comprehensive --history --verbose

# Performance threshold testing
credl benchmark --threshold 100 --format json --output results.json

# Compare with previous results
credl benchmark --compare previous-results.json --format table
```

#### Benchmark Suites

**quick** (3 test files, 5 iterations):
- Basic parsing tests
- Simple validation tests
- Minimal IR generation
- ~30 seconds total

**standard** (8 test files, 10 iterations):
- Parser performance
- Validation performance
- IR generation performance
- Template resolution
- Preset resolution
- ~2 minutes total

**comprehensive** (15 test files, 20 iterations):
- All standard tests
- Large file processing
- Complex template scenarios
- Concurrent processing
- Memory usage analysis
- ~10 minutes total

#### Output Formats

**table** (default):
```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           CREDL Benchmark Results                           │
├─────────────────────────────────────────────────────────────────────────────┤
│ Suite: standard                                    │ Date: 2025-01-21 10:30 │
│ Iterations: 10                                     │ Warmup: 3               │
└─────────────────────────────────────────────────────────────────────────────┘

┌──────────────────────┬─────────┬─────────┬─────────┬─────────┬─────────────┐
│ Test                 │   Min   │   Max   │  Mean   │ Std Dev │   Memory    │
├──────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────────┤
│ Parse 25 spaces      │  23ms   │  45ms   │  31ms   │  6.2ms  │   2.1 MB    │
│ Validate 25 spaces   │  18ms   │  32ms   │  24ms   │  4.1ms  │   1.8 MB    │
│ Generate IR 25 spaces│  35ms   │  67ms   │  48ms   │  8.9ms  │   3.2 MB    │
│ Resolve Templates    │  12ms   │  28ms   │  19ms   │  4.5ms  │   1.2 MB    │
│ Resolve Presets      │   8ms   │  15ms   │  11ms   │  2.1ms  │   0.8 MB    │
│ Process 100 spaces   │  89ms   │ 145ms   │ 112ms   │ 16.8ms  │   8.5 MB    │
│ Large File (500 sp.) │ 234ms   │ 389ms   │ 298ms   │ 42.1ms  │  28.3 MB    │
└──────────────────────┴─────────┴─────────┴─────────┴─────────┴─────────────┘

Performance Summary:
• Average processing speed: ~0.6ms per space
• Memory efficiency: ~0.06MB per space
• Meets performance requirements: ✅ (target: <1000ms for 100 spaces)
• Memory within limits: ✅ (target: <50MB for large files)
```

**json**:
```json
{
  "suite": "standard",
  "timestamp": "2025-01-21T10:30:00Z",
  "iterations": 10,
  "warmup": 3,
  "results": [
    {
      "test": "Parse 25 spaces",
      "min": 23,
      "max": 45,
      "mean": 31,
      "stddev": 6.2,
      "memory": 2.1
    }
  ],
  "summary": {
    "avgProcessingSpeed": 0.6,
    "memoryEfficiency": 0.06,
    "meetsPerformanceRequirements": true,
    "memoryWithinLimits": true
  }
}
```

**csv**:
```csv
Test,Min (ms),Max (ms),Mean (ms),Std Dev (ms),Memory (MB)
Parse 25 spaces,23,45,31,6.2,2.1
Validate 25 spaces,18,32,24,4.1,1.8
Generate IR 25 spaces,35,67,48,8.9,3.2
...
```

#### Exit Codes
- `0` - Benchmarks completed successfully
- `1` - Performance threshold exceeded
- `2` - Benchmark configuration errors
- `3` - Benchmark execution errors

---

## Output Formats

### JSON Format
Standard JSON output with full data structure. Suitable for programmatic processing and integration with other tools.

### Pretty Format
Human-readable formatted output with colors, tables, and visual indicators. Ideal for console output and development.

### Table Format
Tabular output with aligned columns. Good for validation results and benchmark comparisons.

### Summary Format
Concise one-line summaries. Perfect for batch processing and quick status checks.

### CSV Format
Comma-separated values for data analysis and reporting. Available for benchmark results.

## Exit Codes

All CREDL CLI commands follow standard Unix exit code conventions:

| Code | Meaning | Commands |
|------|---------|----------|
| `0` | Success | All commands |
| `1` | Validation/Test failures | validate, run, test |
| `2` | File not found | run, validate, convert |
| `3` | Processing/Execution errors | All commands |
| `4` | Configuration errors | test, benchmark |
| `5` | Performance threshold exceeded | benchmark |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `CREDL_MAX_MEMORY` | Maximum memory limit (MB) | 1024 |
| `CREDL_TIMEOUT` | Processing timeout (ms) | 30000 |
| `CREDL_LOG_LEVEL` | Log level: error, warn, info, debug | info |
| `CREDL_TEMP_DIR` | Temporary directory for processing | OS temp |
| `NODE_OPTIONS` | Node.js options (e.g., --max-old-space-size) | - |

### Example Usage
```bash
# Set memory limit
export CREDL_MAX_MEMORY=2048
credl run large-property.credl

# Enable debug logging
export CREDL_LOG_LEVEL=debug
credl validate my-property.credl --verbose

# Increase Node.js memory
export NODE_OPTIONS="--max-old-space-size=4096"
credl benchmark --suite comprehensive
```

## Configuration Files

The CREDL CLI supports configuration files for default options and settings.

### .credlrc
JSON configuration file in project root:

```json
{
  "defaultFormat": "pretty",
  "validateReferences": true,
  "resolvePresets": true,
  "resolveTemplates": true,
  "includeMetadata": true,
  "benchmarkSuite": "standard",
  "testTimeout": 30000,
  "outputDirectory": "./output"
}
```

### package.json
Configuration in package.json:

```json
{
  "credl": {
    "defaultFormat": "json",
    "validateReferences": true,
    "testPattern": "**/*.test.ts",
    "benchmarkIterations": 10
  }
}
```

## Examples

### Complete Development Workflow
```bash
# 1. Initialize new project
credl init --type office --name "Downtown Tower" --location "Chicago, IL"

# 2. Validate the generated file
credl validate downtown-tower.credl --format table --verbose

# 3. Process the file
credl run downtown-tower.credl --format pretty --verbose

# 4. Convert to IR for analysis
credl convert downtown-tower.credl --output downtown-tower-ir.json

# 5. Run tests
credl test --examples --coverage

# 6. Benchmark performance
credl benchmark --file downtown-tower.credl --memory
```

### CI/CD Pipeline
```bash
# Validate all CREDL files in repository
credl validate **/*.credl --format json --output validation-report.json --exit-code

# Run all tests in CI mode
credl test --ci --coverage --max-workers 4

# Benchmark with performance thresholds
credl benchmark --suite standard --threshold 100 --format json --output benchmark-report.json
```

### Batch Processing
```bash
# Validate multiple files
for file in properties/*.credl; do
  echo "Validating $file..."
  credl validate "$file" --format summary
done

# Process multiple files to IR
mkdir -p output
for file in properties/*.credl; do
  basename=$(basename "$file" .credl)
  credl convert "$file" --output "output/${basename}-ir.json"
done
```

## Troubleshooting

### Common Issues

#### Command Not Found
```bash
# Check installation
npm list -g credl-parser-evaluator

# Reinstall if necessary
npm install -g credl-parser-evaluator

# Use npx as alternative
npx credl-parser-evaluator --help
```

#### Permission Errors
```bash
# Configure npm prefix (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
```

#### Memory Issues
```bash
# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
credl run large-file.credl

# Use streaming for large files
credl convert large-file.credl --skip-validation --format json
```

#### Performance Issues
```bash
# Skip validation for faster processing
credl run my-property.credl --skip-validation

# Disable reference validation
credl run my-property.credl --validate-references false

# Use minimal processing options
credl convert my-property.credl --include-metadata false --generate-ids false
```

### Debug Mode
```bash
# Enable verbose output
credl run my-property.credl --verbose

# Enable debug logging
export CREDL_LOG_LEVEL=debug
credl validate my-property.credl --verbose

# Profile performance
credl benchmark --file my-property.credl --profile --verbose
```

### Getting Help
- Use `--help` with any command for detailed options
- Check the main README.md for library usage
- See examples/ directory for sample CREDL files
- Use `--verbose` flag for detailed processing information
- Run `credl benchmark` to identify performance bottlenecks

---

*CREDL CLI Reference - Comprehensive command-line interface for CREDL processing and analysis.*