dtl-js/docs/DTL-cli.md

Data Transformation Language - JSON templates and data transformation

# DTL Command Line Tool Documentation

## Overview
The `dtl` command line tool excels in bulk data processing, capable of handling
YAML, JSON, CSV, and plain text formats. It automatically detects data types
based on file extensions and is ideal for ETL operations, data format
conversions, and applying DTL transforms.

## Usage
Basic syntax for the `dtl` tool:
```
dtl [options] inputfile
```

### Key Features
- **Automatic Data Type Detection**: The tool automatically detects input and output data types based on file extensions.
- **Default Output**: By default, outputs JSON to stdout. Output is colorized and pretty-printed when run interactively.
- **File-Based Output**: Outputs compact JSON to files, unless overridden with `--pretty n`.

### Options
- `-e --execute '$.'`: Execute a DTL transform from the command line.
- `-f --transform-file`: Load a DTL transformation from a file.
- `-n --transform`: Specify the name of the transform to use (default: "out").
- `-a --apply_to_array`: Apply the transform to each item in an input array.

#### Output Formatting
- `-p --pretty [n]`: Produce pretty JSON output, indented by `n` spaces.
- `-c --condensed`: Output condensed JSON.
- `-N --preserve-undefined`: Preserve `undefined` as `null` in JSON output.

#### Initialization
- `--init <init_file>`: Initialize DTL with contents from `init_file`.

#### Reading Modes
- `-m --read-mode <mode>`: Choose read mode (`line` or `all`).
- `-d --delim <char>`: Specify the output delimiter (for CSV and Unix formats).
- `-id --idelim <char>`: Specify the input delimiter (for CSV and Unix formats).

#### File Handling
- `-o --output-file <file>`: Direct output to a specified file.
- `-I --input-type`, `-O --output-type`: Override default input/output type detection.

#### Special Modes
- `-u --unix`: Treat input/output as Unix-style plaintext.
- `-C --csv-columns`: Specify columns for CSV output.
- `-S --skipheader`: Omit header line in CSV output.
- `-s --strict-json`: Enforce strict JSON parsing.

#### Version Information
- `-V --version`: Show DTL version.

## Examples

1. **Simple CSV to JSON Conversion**:
   ```
   dtl myfile.csv
   ```
   Converts `myfile.csv` to colorized, pretty-printed JSON on stdout.

2. **JSON to YAML**:
   ```
   dtl -o output.yaml input.json
   ```
   Loads `input.json` and outputs the same structure as YAML in `output.yaml`.

3. **JSON to YAML with Transformation File**:
   ```
   dtl -f transform.dtl input.json output.yaml
   ```
   Applies transformations from `transform.dtl` to `input.json` and outputs as YAML in `output.yaml`.

4. **Unix Text to Pretty JSON in File**:
   ```
   dtl -I unix -o output.json --pretty 2 unixdata.txt
   ```
   Converts Unix-style text from `unixdata.txt` to pretty JSON with 2-space indentation in `output.json`.

5. **YAML to Condensed JSON**:
   ```
   dtl -c data.yaml
   ```
   Converts `data.yaml` to condensed JSON output on stdout.