hedl-cli

The complete command-line toolkit for HEDL.

HEDL files are more compact than JSON, more readable than YAML, and more structured than CSV. But a file format is only as good as the tools that surround it. hedl-cli gives you everything you need to work with HEDL at scale: validation, formatting, linting, structure inspection, format conversion, and batch processing with parallel execution.

Whether you're validating schemas in CI, converting database exports, analyzing token efficiency for LLM contexts, or processing thousands of configuration files, this is your tool.

Installation

# From source
cargo install hedl-cli

# Or build locally
cd crates/hedl-cli
cargo build --release

The binary is named hedl and lives at target/release/hedl.

Core Commands

validate

Check that your HEDL files are syntactically correct and structurally sound.

hedl validate config.hedl
hedl validate --strict api_schema.hedl

The --strict flag ensures all entity references resolve to defined entities. Without it, forward references are allowed. Exit code 0 means valid; exit code 1 means something's wrong.

Output looks like:

✓ config.hedl
  Version: 1.0
  Structs: 5
  Aliases: 2
  Nests: 3

format

Normalize HEDL files to canonical form.

hedl format data.hedl                    # Output to stdout
hedl format data.hedl -o formatted.hedl  # Output to file
hedl format --check config.hedl          # Check without writing
hedl format --with-counts users.hedl     # Add count hints to matrix lists

The --check flag is perfect for CI: it exits with code 1 if the file isn't already canonical, without modifying anything. The --with-counts flag recursively adds count hints to all matrix lists, showing you exactly how many rows each contains.

lint

Check your files against best practices.

hedl lint schema.hedl
hedl lint --format json config.hedl
hedl lint --warn-error critical.hedl

Text output with colors:

Warning [unused-alias]: Alias 'old_api' is defined but never used
  at line 15

Suggestion [add-count-hints]: Matrix list 'users' is missing count hint
  at line 42

Found 1 warning, 1 suggestion

JSON output for programmatic processing:

{
  "issues": [
    {
      "severity": "warning",
      "rule": "unused-alias",
      "message": "Alias 'old_api' is defined but never used",
      "line": 15
    }
  ],
  "summary": {
    "errors": 0,
    "warnings": 1,
    "suggestions": 1
  }
}

Use --warn-error to fail the build on warnings, not just errors.

inspect

Visualize the structure of a HEDL document as a tree.

hedl inspect data.hedl
hedl inspect -v schema.hedl  # Verbose: show field values

Document (1.0)
├─ Schemas (3)
│  ├─ User [id, name, email, created_at]
│  ├─ Post [id, author, title, content]
│  └─ Comment [id, post, author, text]
├─ Aliases (2)
│  ├─ $api_url = "https://api.example.com"
│  └─ $version = "2.1.0"
├─ Nests (1)
│  └─ Post > Comment
└─ Data
   ├─ users: @User (125 entities)
   ├─ posts: @Post (48 entities)
   └─ comments: @Comment (312 entities)

With -v, you get the actual data:

└─ users: @User (3 entities)
   ├─ alice [Alice Smith, alice@example.com, 2024-01-15]
   ├─ bob [Bob Jones, bob@example.com, 2024-02-20]
   └─ carol [Carol White, carol@example.com, 2024-03-10]

stats

Compare HEDL file sizes and token counts against JSON, YAML, and XML.

hedl stats data.hedl
hedl stats --tokens config.hedl  # Include LLM token estimates

Format Comparison for 'data.hedl':

File Sizes:
  HEDL:         2,458 bytes
  JSON (compact): 3,841 bytes  (+56.3%)
  JSON (pretty):  5,219 bytes  (+112.3%)
  YAML:         4,105 bytes  (+67.0%)
  XML:          6,732 bytes  (+173.9%)

Token Estimates (LLM ~4 chars/token):
  HEDL:         615 tokens
  JSON (compact): 960 tokens   (+56.1%)
  JSON (pretty):  1,305 tokens (+112.2%)
  YAML:         1,026 tokens  (+66.8%)
  XML:          1,683 tokens  (+173.7%)

Conclusion: HEDL saves 345 tokens (36%) vs JSON compact, 690 tokens (53%) vs JSON pretty

All format conversions run in parallel for maximum throughput.

Format Conversion

Bidirectional conversion between HEDL and six popular formats: JSON, YAML, XML, CSV, Parquet, and TOON.

JSON

hedl to-json data.hedl -o output.json
hedl to-json --pretty data.hedl          # Pretty-printed
hedl to-json --metadata schema.hedl      # Include HEDL version and schema info
hedl from-json input.json -o output.hedl

YAML

hedl to-yaml config.hedl -o config.yml
hedl from-yaml config.yml -o config.hedl

XML

hedl to-xml data.hedl -o output.xml
hedl to-xml --pretty data.hedl
hedl from-xml input.xml -o output.hedl

CSV

hedl to-csv users.hedl -o users.csv
hedl from-csv --type-name User input.csv -o users.hedl

The --type-name flag specifies the entity type name when converting from CSV (defaults to "Row").

Parquet

hedl to-parquet data.hedl --output output.parquet
hedl from-parquet input.parquet -o data.hedl

Parquet uses binary columnar format, so --output is required.

TOON

hedl to-toon data.hedl -o output.toon
hedl from-toon input.toon -o data.hedl

TOON (Token-Oriented Object Notation) was designed for LLM efficiency, but accuracy testing shows HEDL achieves higher comprehension (+12.2pp average) with 7% fewer tokens.

Batch Processing

Process hundreds or thousands of files in parallel with automatic parallelization and progress tracking.

batch-validate

hedl batch-validate data/*.hedl
hedl batch-validate --strict schemas/*.hedl
hedl batch-validate -v configs/*.hedl              # Verbose progress
hedl batch-validate --streaming large-files/*.hedl # Constant memory for huge files
hedl batch-validate --auto-streaming mixed/*.hedl  # Auto-detect when to stream
hedl batch-validate --max-files 5000 huge-dir/*.hedl

Validating 127 files...
Progress: [========================================] 127/127 (100%)
Completed in 2.3s (55 files/sec)

Results:
  Valid: 125 files
  Failed: 2 files
    - data/broken.hedl: Parse error at line 42: unexpected token
    - schemas/old.hedl: Unresolved reference @User:nonexistent

Parallelization kicks in automatically when processing 10+ files. Expect 3-5x speedup on multi-core systems.

batch-format

hedl batch-format data/*.hedl
hedl batch-format configs/*.hedl --output-dir formatted/
hedl batch-format --with-counts schemas/*.hedl

Formatting 89 files...
Progress: [========================================] 89/89 (100%)
Completed in 1.8s (49 files/sec)

Results:
  Formatted: 87 files
  Unchanged: 0 files (already canonical)
  Failed: 2 files
    - data/corrupt.hedl: Parse error at line 15

batch-lint

hedl batch-lint data/*.hedl
hedl batch-lint --warn-error schemas/*.hedl
hedl batch-lint -v configs/*.hedl

Linting 64 files...
Progress: [========================================] 64/64 (100%)
Completed in 1.1s (58 files/sec)

Aggregated Results:
  Errors: 3 across 2 files
  Warnings: 12 across 8 files
  Suggestions: 25 across 19 files

Top Issues:
  - unused-alias (8 occurrences)
  - add-count-hints (7 occurrences)
  - unresolved-reference (3 occurrences)

Failed Files:
  - schemas/old.hedl: 2 errors, 3 warnings
  - configs/broken.hedl: 1 error

Shell Completion

Generate completion scripts for your shell.

hedl completion bash > ~/.hedl-completion.bash
hedl completion zsh > ~/.hedl-completion.zsh
hedl completion fish > ~/.config/fish/completions/hedl.fish
hedl completion powershell
hedl completion elvish

Add source ~/.hedl-completion.bash to your .bashrc, then enjoy tab completion for all commands, subcommands, and options.

hedl <TAB>           # Shows all commands
hedl batch-<TAB>     # Shows batch-validate, batch-format, batch-lint
hedl validate --<TAB> # Shows --strict option

Security

File Size Limits

By default, hedl-cli refuses to process files larger than 1 GB to prevent memory exhaustion. Configure this via environment variable:

export HEDL_MAX_FILE_SIZE=2147483648  # 2 GB

Input Validation

Type names (for CSV conversion) accept only alphanumeric characters and underscores. All file paths are validated before processing. Batch operations continue processing other files when individual files fail.

Error Context

Errors include detailed context to help you fix problems quickly:

Error: Failed to parse 'data/broken.hedl'
  Parse error at line 42, column 15:
    unexpected token ']', expected field name

  Context:
    40 | users: @User[id, name]
    41 |   | alice, Alice Smith
    42 |   | bob, Bob Jones]
       |                     ^ here

Performance

Validation runs at 100-200 MB/s. Formatting at 50-100 MB/s. Linting at 80-150 MB/s. Batch operations with parallelization see 3-5x speedup on multi-core systems.

Memory usage is O(document_size) per file since documents are fully parsed. For streaming large files (>100 MB), use the --streaming flag or the hedl-stream crate directly.

License

Apache-2.0