TOON (Token-Oriented Object Notation) is a data serialization format designed specifically for LLM prompts to be highly efficient. It dramatically reduces token usage by 30-60% compared to JSON while remaining structured and human-readable. By using a tabular format for arrays and minimal syntax for objects, TOON makes your data cheaper and faster to process with AI models.

What's the difference between TOON and JSON?

The key difference is token efficiency. JSON is verbose, with brackets, quotes, and commas that consume tokens. TOON is a more compact syntax designed for LLMs, representing arrays as tables with headers and using minimal punctuation. This efficiency directly translates to significant cost savings on your LLM API bills, especially for large or repeated datasets.

How much can I save with TOON?

You can typically expect to save 30-60% on LLM tokens compared to using JSON. For large datasets or frequent API calls, this translates directly into significant cost savings. Data with repeated structures, like API responses or database results, often sees savings at the higher end of this range (40-60%).

Is TOON compatible with all LLMs?

Yes. TOON is a simple text format that works flawlessly with all major large language models, including those from OpenAI (GPT-4), Anthropic (Claude), Google (Gemini), and Meta (LLaMA). Since any LLM can process plain text, they can all be instructed to understand and parse the TOON format with a simple instruction in your prompt.

Can I convert TOON back to JSON?

Absolutely. TOON is fully and losslessly reversible. Our converter tool supports bidirectional conversion, meaning you can convert TOON back to the exact original JSON structure without any data loss. This allows you to use TOON for efficiency and then convert back to JSON for compatibility with other tools.

What types of data work best with TOON?

TOON can represent any valid JSON data, but it delivers the highest token savings (40-60%) on uniform tabular data. This includes database query results, API responses with lists of objects, analytics data, or product catalogs. While TOON fully supports nested objects and arrays, the token reduction is most dramatic with flatter, more repetitive data structures.

Is my data safe when using this converter?

100% safe. All conversion from JSON to TOON (and back) happens locally in your browser. Your data is never sent to any server, never stored, and never seen by us. The converter even works offline once the page has loaded, guaranteeing your information remains private.

Yes, completely free. Both this TOON converter and the underlying TOON format specification are open and free to use without any limits, file size restrictions, or premium features. It's an open-source effort to make working with LLMs more efficient for everyone.

Mastering the TOON CLI

CLI

TOON

If you have been working with Large Language Models (LLMs), you know that JSON is the lingua franca of data exchange. However, you also know that JSON is notoriously "chatty." All those braces, quotes, and repeated keys eat up your context window, increase latency, and drive up API costs.

This is where TOON (The Object-Oriented Notation) shines. While the TypeScript library is great for application code, sometimes you just need to get things done quickly in the terminal. Whether you are debugging a prompt, preparing a dataset, or simply curious about how much money you could save on tokens, the @toon-format/toon CLI is your new best friend.

In this guide, we will look at how to leverage the TOON Command Line Interface to integrate data optimization directly into your shell workflows.

Getting Set Up

One of the best things about modern JavaScript tooling is that you often don't need to "install" anything to get started. If you just want to try TOON out on a single file, you can use npx to run the binary directly:

npx @toon-format/cli input.json -o output.toon

However, if you are planning to use this frequently—and once you see the token savings, you likely will—a global installation is the way to go. It gives you access to the concise toon command anywhere in your system.

npm install -g @toon-format/cli
# or
pnpm add -g @toon-format/cli

Once installed, you are ready to start shrinking your data.

The Magic of Auto-Detection

The TOON CLI is designed to be smart about what you are trying to do. You rarely need to explicitly tell it to encode or decode; it looks at your file extensions to decide.

If you feed it a .json file, it assumes you want to encode it to TOON. If you provide a .toon file, it switches to decoding mode to give you back JSON.

# Automatically encodes to TOON
toon data.json -o compressed.toon

# Automatically decodes to JSON
toon compressed.toon -o restored.json

But where the CLI really proves its worth is in the "Unix philosophy"—small tools loosely joined. Because the TOON CLI reads from standard input (stdin) and writes to standard output (stdout), you can pipe data directly through it.

# Pipe JSON directly into TOON
cat large-dataset.json | toon > data.toon

# Echo a quick object to see how it looks in TOON
echo '{"name": "Ada", "role": "admin"}' | toon

When you are piping data via stdin, the CLI defaults to encode mode. If you need to decode a stream of TOON data coming from another process, simply add the --decode (or -d) flag.

Analyzing Token Savings

Optimizing data formats is often about guessing games. "If I remove whitespace, how much do I save?" "What if I switch to YAML?"

The TOON CLI eliminates the guesswork with the --stats flag. When encoding, this option calculates the estimated token count and shows you the savings immediately. This is invaluable when you are budgeting for high-volume LLM calls.

toon context.json --stats

You might see output indicating a 30% or 40% reduction in size. That isn't just disk space; that is 40% less latency and 40% lower cost on input tokens.

Advanced Tuning: Delimiters and Formatting

By default, TOON uses commas to separate array items, similar to JSON. However, different LLM tokenizers behave differently with punctuation. Sometimes, a tab character or a pipe (|) is more token-efficient than a comma.

The CLI allows you to swap delimiters on the fly. If you are dealing with tabular data, switching to a tab delimiter can make the output look cleaner and process more efficiently.

For a list of products, this transforms the output from a comma-separated list to a clean, tab-separated structure that looks almost like a spreadsheet, which many models parse exceptionally well.

# Use tabs for array items
toon items.json --delimiter "\t" -o items.toon

::: tip Pro Tip: Tab delimiters often reduce the need for escaping quotes and can result in better tokenization for numerical data. If you are processing massive datasets, try --delimiter "\t" to squeeze out every bit of efficiency. :::

Compressing Structure with Key Folding

One of the newer features (introduced in spec v1.5) available in the CLI is Key Folding. JSON data is often deeply nested, with wrapper keys like data.response.items that add structural depth without adding meaning.

The CLI allows you to "fold" these nested keys into a single dot-notated path, flattening the hierarchy and saving tokens on indentation and braces.

toon deep-structure.json --key-folding safe -o flat.toon

This transforms nested objects:

{ "user": { "profile": { "id": 1 } } }

Into a concise TOON representation:

user.profile.id: 1

If you need to convert this back to full JSON later, you can use the --expand-paths safe flag during decoding to reconstruct the deep object structure perfectly.

integrating into Pipelines

The real power of the TOON CLI comes when you chain it with other tools like curl and jq. You can fetch data from an API, filter it down to the essentials, and convert it to TOON in a single line—ready to be pasted into a prompt or sent to an inference endpoint.

In this workflow, you fetch the data, extract only the active users, convert it to a pipe-delimited TOON format, and get a stats report on how many tokens you just saved.

curl -s https://api.example.com/users \
  | jq '.data.active_users' \
  | toon --stats --delimiter "|"

Summary

The @toon-format/cli is more than just a file converter; it is a utility belt for the LLM era. By moving data processing to the command line, you can iterate faster, visualize optimizations immediately, and integrate token-efficient formats into your existing engineering workflows.

Whether you are preparing RAG (Retrieval-Augmented Generation) documents or simply trying to fit a massive JSON blob into a small context window, give the CLI a spin. Your token budget will thank you.