3.4 KiB
@toon-format/cli
Command-line tool for converting between JSON and TOON formats.
TOON (Token-Oriented Object Notation) is a compact, human-readable serialization format designed for passing structured data to Large Language Models with significantly reduced token usage.
Installation
# npm
npm install -g @toon-format/cli
# pnpm
pnpm add -g @toon-format/cli
# yarn
yarn global add @toon-format/cli
Or use directly with npx:
npx @toon-format/cli [options] [input]
Usage
toon [options] [input]
Standard input: Omit the input argument or use - to read from stdin. This enables piping data directly from other commands.
Auto-detection: The CLI automatically detects the operation based on file extension (.json → encode, .toon → decode). When reading from stdin, use --encode or --decode flags to specify the operation (defaults to encode).
Basic Examples
# Encode JSON to TOON (auto-detected)
toon input.json -o output.toon
# Decode TOON to JSON (auto-detected)
toon data.toon -o output.json
# Output to stdout
toon input.json
# Pipe from stdin
cat data.json | toon
echo '{"name": "Ada"}' | toon
# Decode from stdin
cat data.toon | toon --decode
Options
| Option | Description |
|---|---|
-o, --output <file> |
Output file path (prints to stdout if omitted) |
-e, --encode |
Force encode mode (overrides auto-detection) |
-d, --decode |
Force decode mode (overrides auto-detection) |
--delimiter <char> |
Array delimiter: , (comma), \t (tab), | (pipe) |
--indent <number> |
Indentation size (default: 2) |
--length-marker |
Add # prefix to array lengths (e.g., items[#3]) |
--stats |
Show token count estimates and savings (encode only) |
--no-strict |
Disable strict validation when decoding |
Advanced Examples
Token Statistics
Show token savings when encoding:
toon data.json --stats -o output.toon
Example output:
✓ Encoded to TOON
Input: 15,145 tokens (JSON)
Output: 8,745 tokens (TOON)
Saved: 6,400 tokens (42.3% reduction)
Alternative Delimiters
Tab-separated (often more token-efficient)
toon data.json --delimiter "\t" -o output.toon
Pipe-separated with length markers
toon data.json --delimiter "|" --length-marker -o output.toon
Lenient Decoding
Skip validation for faster processing:
toon data.toon --no-strict -o output.json
Stdin Workflows
# Convert API response to TOON
curl https://api.example.com/data | toon --stats
# Process large dataset
cat large-dataset.json | toon --delimiter "\t" > output.toon
# Chain with other tools
jq '.results' data.json | toon > filtered.toon
Why Use the CLI?
- Quick conversions between formats without writing code
- Token analysis to see potential savings before sending to LLMs
- Pipeline integration with existing JSON-based workflows
- Flexible formatting with delimiter and indentation options
Related
- @toon-format/toon - JavaScript/TypeScript library
- Full specification - Complete format documentation
- Website - Interactive examples and guides
License
MIT License © 2025-PRESENT Johann Schopplich