Guide · Open source
How to use TOON: install the toon-format SDK and CLI
Updated · written with AI from the project's own documentation and checked against our catalogue data
TOON (Token-Oriented Object Notation) is an open-source text format that represents JSON data in fewer characters, so it uses fewer tokens when you paste structured data into a large language model prompt. It is written to stay readable by humans. This guide shows you how to install the TypeScript package, where the SDK, command-line tool and benchmarks fit in, and how to decide whether TOON is worth using for your prompts.
TOONtoon-format/toon · ★ 25.6k · MIT Install options & downloads Quick start
- 1Check Node.js. Make sure Node.js is installed, since it is the listed prerequisite for the package.
- 2Install the package. Run npm install @toon-format/toon in your project folder.
- 3Import the SDK. Use the TypeScript SDK from the installed package in your code, following the README for the exact names.
- 4Encode a JSON payload. Convert the JSON data you plan to send to an LLM into TOON text.
- 5Convert files if needed. Use the command-line tool to convert JSON files to TOON, using the options in the README.
- 6Run the benchmarks. Compare token counts for TOON and JSON on your own data before adopting it.
What TOON is and why it reduces tokens
TOON is a text format for JSON data. Because it uses fewer characters for the same data, a prompt that contains it takes up fewer tokens than the equivalent JSON. Fewer tokens can mean lower usage when you send large structured payloads to an LLM.
The format is meant to stay readable by people, so you can still inspect the data by eye.
- Purpose: compact representation of JSON for LLM prompts
- Readability: designed to be readable by humans
- Scope: the main benefit is in prompts, not service-to-service data exchange
Install the toon package with npm
The project is distributed as a package and requires Node.js. Install the package into your project with npm using the package name from the project README.
Once installed, the package gives you the TypeScript SDK that you can use to encode and decode the format.
- Prerequisite: Node.js
- Package name: @toon-format/toon
npm install @toon-format/toonUse the TypeScript SDK to encode and decode
The project provides a TypeScript SDK for encoding JSON data into TOON and decoding TOON back into data. If your team already works in TypeScript, the SDK is the most direct way to put TOON into your prompt-building code.
Check the README in the repository and the project homepage for the exact function names and usage examples, since this guide does not list them.
- Encode: turn JSON data into TOON text before adding it to a prompt
- Decode: read TOON text back into data
Convert JSON files with the command-line tool
The project includes a command-line tool for converting JSON files to TOON. Use it when you want to prepare data files outside your code, for example before pasting them into a chat or prompt.
Refer to the project README for the exact command and options, as they are not covered in this guide.
- Input: JSON files
- Output: TOON
Measure your token savings with the benchmarks
The repository includes benchmarks that compare TOON with JSON. Run them on your own kind of data before you decide to switch, because savings depend on the shape of the data you send.
The benchmark results in the README are the project's own; check your own token counts with the tokenizer your LLM uses.
- Compare: TOON against JSON
- Decide: based on your own data, not only on published numbers
Know when TOON is not the right choice
TOON is aimed at prompts. If your project only moves data between services and does not use an LLM, the token savings give you no benefit. The README describes a TypeScript SDK, and support in other languages is not clear from the provided text, so check before relying on it in a non-TypeScript stack.
- Skip it for service-to-service data that never reaches an LLM
- Check language support if your stack is not TypeScript
What people use it for
- Sending large structured JSON records to an LLM prompt in a TypeScript application
- Converting JSON files to TOON from the command line before pasting them into a prompt
- Measuring how many tokens TOON saves compared with JSON using the included benchmarks
- Encoding and decoding TOON inside a TypeScript team's tooling
Frequently asked questions
How do I install toon?
Install Node.js first, then run npm install @toon-format/toon in your project folder. The package provides the TypeScript SDK.
Is TOON free to use?
TOON is released under the MIT licence, as listed on the project page. Check the licence file in the repository for the full terms.
What do I need to run TOON?
The listed prerequisite is Node.js. The project is written in TypeScript and provides a TypeScript SDK.
Does TOON save money on LLM calls?
TOON uses fewer tokens than JSON for the same data, which can reduce usage on prompts. The size of the saving depends on your data, so run the included benchmarks on your own payloads.
What are alternatives to TOON?
The project lists JSON, YAML and MessagePack as comparable formats. JSON is the format TOON represents, so it is the closest baseline to compare against.
Can I use TOON outside TypeScript?
The README describes a TypeScript SDK, and support in other languages is unclear from the provided text. Check the project homepage and repository before using it in another language.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
TOON is a good fit if you are a developer who sends structured JSON to LLM prompts and wants fewer tokens, especially in a TypeScript project. If you only exchange data between services, or need broad multi-language support that the README does not clearly provide, pick JSON, YAML or MessagePack instead.
Install options & downloads