CLI Reference

This document defines the verifiable contracts for each ExactEDI CLI command. These contracts are stable guarantees - breaking them is a major version change.

Global Exit Codes

Global Options (all commands)

--verbose, -v       Enable debug-level logging
--quiet, -q         Suppress info messages (errors only)
--log-file <path>   Write detailed logs to file
--help, -h          Show command help

parse <file>

Purpose: Parse X12 file and emit JSONL segment stream.

Contract

JSONL Schema (v1.0)

Each line is a JSON object with guaranteed fields:

{
  "seg": "string",           // REQUIRED: Segment ID (e.g., "ISA", "NM1")
  "elem": ["string", ...],   // REQUIRED: Array of element values
  "pos": {                   // OPTIONAL: Present unless --no-position
    "byte": 0,               // Byte offset in source file
    "idx": 0                 // Zero-based segment index
  },
  "isa_ctrl": "string",      // OPTIONAL: ISA13 control number (within interchange)
  "gs_ctrl": "string",       // OPTIONAL: GS06 control number (within group)
  "st_ctrl": "string"        // OPTIONAL: ST02 control number (within transaction)
}

Schema version header (with --schema-version):

{"_schema":"exactedi-jsonl","_version":"1.0.0","_engine":"1.2.3"}

Options

--output, -o <path>    Write output to file instead of stdout
--stdout               Force stdout output (explicit, useful in scripts)
--max-errors <N>       Stop after N parse errors (default: unlimited)
                       Use 1 for fail-fast, 0 for unlimited
--schema-version       Emit schema version as first record
--no-position          Omit position information from output
--no-envelope          Omit envelope context (isa_ctrl, gs_ctrl, st_ctrl)

Examples

# Basic usage - stdout
exactedi parse claims.edi

# Write to file
exactedi parse claims.edi --output claims.jsonl

# Fail-fast mode
exactedi parse claims.edi --max-errors 1

# With schema header for downstream consumers
exactedi parse claims.edi --schema-version > claims.jsonl

# Pipe to jq for filtering
exactedi parse claims.edi | jq 'select(.seg == "NM1")'

validate <file>

Purpose: Validate X12 file structural integrity.

Contract

Text Output Format

File: claims.edi
Valid: Yes|No
Segments: <count>
Interchanges: <count>
Groups: <count>
Transactions: <count>
Errors: <count>
Warnings: <count>

Diagnostics:
  [ERROR] <code>: <message> at byte <offset>
  [WARN]  <code>: <message> at byte <offset>

JSON Output Schema (v1.0)

{
  "_schema": "exactedi-validation",
  "_version": "1.0.0",
  "file": "string",
  "valid": true|false,
  "summary": {
    "segments": 0,
    "interchanges": 0,
    "groups": 0,
    "transactions": 0,
    "errors": 0,
    "warnings": 0
  },
  "diagnostics": [
    {
      "severity": "error"|"warning",
      "code": "string",
      "message": "string",
      "byte_offset": 0,
      "segment_index": 0
    }
  ]
}

Strictness Levels

Strict mode enables:

• Exact segment count verification (SE01, GE01, IEA01)
• Control number matching (ST02/SE02, GS06/GE02, ISA13/IEA02)
• Required segment presence validation

Options

--strict               Enable strict validation mode
--json                 Output as JSON (deprecated, use --format json)
--format <fmt>         Output format: text (default), json
--report <path>        Write report to file
--max-errors <N>       Stop after N errors (default: unlimited)

Examples

# Basic validation
exactedi validate claims.edi

# Strict mode with JSON output
exactedi validate claims.edi --strict --format json

# Write JSON report to file
exactedi validate claims.edi --format json --report validation.json

# CI/CD integration - fail-fast
exactedi validate claims.edi --strict --max-errors 1

explain <file>

Purpose: Generate PHI-safe Facts JSON summary for analytics and LLM integration.

Contract

PHI Safety Guarantees

Included (Safe Harbor compliant):

• File hash, size, timestamp
• Delimiter characters
• Envelope counts (ISA/GS/ST counts)
• Transaction type counts (837P/837I/837D/835)
• Validation error/warning codes
• CAS group/reason code summaries
• Procedure/diagnosis code statistics (counts only)
• Structural anomaly flags

Never included:

• Patient names, DOB, SSN, MRN
• Member IDs, subscriber IDs
• Provider names (NM1 names)
• Free-text fields
• Raw EDI content
• Address information

Facts JSON Schema (v1.0.0)

See facts_json_schema.md for complete schema.

Root structure:

{
  "schema_version": "1.0.0",
  "engine_version": "1.2.3",
  "file_metadata": { ... },
  "delimiters": { ... },
  "envelope_counts": { ... },
  "transaction_counts": { ... },
  "validation_summary": { ... },
  "cas_summaries": [ ... ],
  "claim_service_counts": { ... },
  "anomalies": { ... }
}

Options

--output, -o <path>    Write output to file instead of stdout
--compact              Compact JSON (no pretty-printing)
--phi-audit            Generate PHI audit trail showing what was excluded

PHI Audit Mode (--phi-audit)

When enabled, generates an additional audit section showing:

• Count of PHI fields detected and excluded
• Categories of excluded data
• Audit timestamp

{
  "phi_audit": {
    "audit_timestamp": "2024-01-15T10:30:00Z",
    "excluded_counts": {
      "patient_names": 5,
      "member_ids": 5,
      "dates_of_birth": 5,
      "addresses": 3
    },
    "safe_harbor_compliant": true
  }
}

Examples

# Generate facts to stdout
exactedi explain claims.edi

# Write to file
exactedi explain claims.edi --output claims_facts.json

# With PHI audit trail
exactedi explain claims.edi --phi-audit --output claims_facts.json

# Compact output for APIs
exactedi explain claims.edi --compact

import <file> --db <sqlite>

Purpose: Import parsed X12 data into SQLite database.

Contract

Database Schema (v1.0)

-- Imported files
CREATE TABLE files (
    id INTEGER PRIMARY KEY,
    filename TEXT NOT NULL,
    file_size INTEGER NOT NULL,
    imported_at TEXT NOT NULL,
    facts_json TEXT
);

-- Segments
CREATE TABLE segments (
    id INTEGER PRIMARY KEY,
    file_id INTEGER NOT NULL REFERENCES files(id),
    segment_index INTEGER NOT NULL,
    segment_id TEXT NOT NULL,
    elements TEXT NOT NULL,  -- JSON array
    byte_offset INTEGER,
    isa_control TEXT,
    gs_control TEXT,
    st_control TEXT
);

-- Indexes
CREATE INDEX idx_segments_file ON segments(file_id);
CREATE INDEX idx_segments_id ON segments(segment_id);

Options

--db, -d <path>        SQLite database file (required)
--batch-size <N>       Segments per transaction (default: 1000)
--schema-version       Print schema version and exit
--help, -h             Show help message

Examples

# Basic import
exactedi import claims.edi --db warehouse.db

# Batch import with larger transactions
exactedi import claims.edi --db warehouse.db --batch-size 5000

# Check schema version
exactedi import --schema-version

normalize <file> --out <dir>

Purpose: Parse X12 file and output normalized structured files.

Contract

Normalization Modes

Output File Naming

Input: /path/to/claims.edi
Output directory: /output/

Mode: full (default)
  /output/claims.jsonl
  /output/claims_facts.json

Mode: split-transactions
  /output/claims_tx_0001.jsonl
  /output/claims_tx_0002.jsonl
  ...
  /output/claims_manifest.json  # Index of all transactions

Manifest Schema (split-transactions mode)

{
  "source_file": "claims.edi",
  "source_size": 12345,
  "transaction_count": 5,
  "transactions": [
    {
      "control_number": "0001",
      "type": "837",
      "output_file": "claims_tx_0001.jsonl",
      "segment_count": 45
    }
  ]
}

Options

--out, -o <dir>        Output directory (required)
--mode <mode>          Normalization mode: full, segments, split-transactions
--schema-version       Include schema version headers in output

Examples

# Default: JSONL + Facts JSON
exactedi normalize claims.edi --out ./normalized/

# Segments only
exactedi normalize claims.edi --out ./normalized/ --mode segments

# Split by transaction
exactedi normalize claims.edi --out ./normalized/ --mode split-transactions

Version Compatibility

Schema Version Policy

• Major version: Breaking changes to output structure
• Minor version: New optional fields (backward compatible)
• Patch version: Bug fixes only

Current Versions

Error Codes Reference

Parse Errors (P-xxx)

Validation Errors (V-xxx)

Validation Warnings (W-xxx)

CI/CD Integration

Exit Code Summary

# Validate before processing
exactedi validate claims.edi --strict
if [ $? -eq 0 ]; then
    echo "Valid"
elif [ $? -eq 1 ]; then
    echo "Error (file/parse issue)"
elif [ $? -eq 2 ]; then
    echo "Invalid (structural issues)"
fi

JSON Output for Automation

# Parse JSON output for downstream processing
result=$(exactedi validate claims.edi --format json)
valid=$(echo "$result" | jq -r '.valid')
errors=$(echo "$result" | jq -r '.summary.errors')