TOON CLI

Token-Optimized Object Notation reduces JSON token counts by 30-50%.

Quick Reference

Convert JSON to TOON

From file

toon data.json -o output.toon

From stdin (pipe from curl, jq, etc.)

curl -s https://api.example.com/data | npx @toon-format/cli

With token statistics

toon data.json --stats

Pipe from jq

jq '.results' data.json | npx @toon-format/cli --stats

Convert TOON to JSON

From file

toon data.toon -o output.json

From stdin

cat data.toon | toon --decode

Common Options

| Option | Description | | --------------------- | --------------------------------------- | --- | | -o, --output <file> | Output file (stdout if omitted) | | -e, --encode | Force encode mode (JSON → TOON) | | -d, --decode | Force decode mode (TOON → JSON) | | --stats | Show token savings (encode only) | | --delimiter <char> | Array delimiter: , (default), \t , | | | --keyFolding safe | Collapse nested objects to dotted paths | | --expandPaths safe | Expand dotted paths when decoding |

Use Cases

Inspect API Response

Quick preview of API data in compact form

curl -s https://api.github.com/users/torvalds | npx @toon-format/cli

With token count comparison

curl -s https://api.github.com/repos/torvalds/linux | npx @toon-format/cli --stats

Process Large JSON Files

Convert large file with streaming (memory efficient)

toon huge-dataset.json -o output.toon

Check token savings before processing

toon large-api-response.json --stats

Optimize for LLM Context

Maximum compression: key folding + tab delimiter

toon data.json --keyFolding safe --delimiter "\t" --stats -o compressed.toon

Round-trip: encode with folding, decode with expansion

toon input.json --keyFolding safe -o compressed.toon toon compressed.toon --expandPaths safe -o restored.json

Pipeline Integration

Filter with jq, compress with toon

jq '.data.items[:10]' response.json | npx @toon-format/cli > subset.toon

Fetch, transform, compress

curl -s https://api.example.com/data | jq '.results' | npx @toon-format/cli --stats

Format Overview

TOON uses indentation instead of braces and brackets, with inline arrays and tabular object arrays:

JSON:

{ "user": { "id": 123, "name": "Ada", "tags": ["admin", "ops"] }, "items": [ { "sku": "A1", "qty": 2, "price": 9.99 }, { "sku": "B2", "qty": 1, "price": 14.5 } ] }

TOON:

user: id: 123 name: Ada tags[2]: admin,ops items[2]{sku,qty,price}: A1,2,9.99 B2,1,14.5

Key Features

• No braces/brackets: Indentation defines structure

• Inline primitive arrays: tags[2]: admin,ops instead of ["admin","ops"]

• Tabular objects: Arrays of uniform objects become CSV-like tables

• Optional key folding: data.metadata.items[2]: a,b instead of nested objects

• Unquoted strings: Only quote when necessary (special chars, delimiters)

Token Savings Example

$ curl -s https://api.github.com/users/torvalds | npx @toon-format/cli --stats

✔ Encoded stdin → stdout

ℹ Token estimates: ~245 (JSON) → ~156 (TOON) ✔ Saved ~89 tokens (-36.3%)

Related

• TOON Specification

• Interactive Playground