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
# Or build locally
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.
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.
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.
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:
Use --warn-error to fail the build on warnings, not just errors.
inspect
Visualize the structure of a HEDL document as a tree.
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.
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
YAML
XML
CSV
The --type-name flag specifies the entity type name when converting from CSV (defaults to "Row").
Parquet
Parquet uses binary columnar format, so --output is required.
TOON
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
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
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
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.
Add source ~/.hedl-completion.bash to your .bashrc, then enjoy tab completion for all commands, subcommands, and options.
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:
# 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