# Format TOML without losing comments

Format TOML in your browser with validation, key sorting, indentation, array layout controls and comment preservation.

## Run it

- **CLI:** `gizza tool toml-formatter "# Package metadata
[package]
name='demo'
version = \"0.1.0\"
features=[\"cli\", \"web\"]"`
- **Web:** https://gizza.ai/tools/toml-formatter/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/toml-formatter/tool.json

## Inputs

- `input` — TOML input _(field)_
- `indent` — Indent spaces _(field)_
- `sort_keys` — Key order _(field)_
- `spacing` — Equals spacing _(field)_
- `array_style` — Array layout _(field)_
- `column_width` — Array width budget _(field)_
- `align_values` — Align equals signs _(field)_
- `blank_line_before_tables` — Blank line before tables _(field)_
- `keep_comments` — Keep comments _(field)_

## Output

- Formatted TOML (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `input` — TOML input
- `indent` — Indent spaces
- `sort_keys` — Key order
- `spacing` — Equals spacing
- `array_style` — Array layout
- `column_width` — Array width budget
- `align_values` — Align equals signs
- `blank_line_before_tables` — Blank line before tables
- `keep_comments` — Keep comments

Example: `https://gizza.ai/tools/toml-formatter/?input=%23%20Package%20metadata%0A%5Bpackage%5D%0Aname%3D%27demo%27%0Aversion%20%3D%20%220.1.0%22%0Afeatures%3D%5B%22cli%22%2C%20%22web%22%5D&indent=0&sort_keys=preserve&spacing=standard&array_style=auto&column_width=80&align_values=true&blank_line_before_tables=true&keep_comments=true`

---

## About this tool

Use this TOML formatter when you want a clean, validated config file without turning it into a lossy value dump. It parses the document first, reports invalid TOML with line and column context, then emits normalized spacing, table ordering, key ordering and array layout according to the options you choose.

Unlike simple value-model formatters, this formatter keeps own-line comments, end-of-line comments, scalar literal spelling such as `0xFF` or `1_000_000`, and literal strings wherever the requested layout can still represent them. That makes it suitable for Cargo.toml, pyproject.toml, taplo.toml and other hand-edited configuration files.

### Worked example

Input:

```toml
# Package metadata
[package]
version="0.1.0"
name='demo' # literal spelling kept
features=["cli","web","docs"]
```

With the defaults, the output becomes:

```toml
# Package metadata
[package]
version = "0.1.0"
name = 'demo' # literal spelling kept
features = ["cli", "web", "docs"]
```

Choose `sort_keys=asc` to alphabetize entries within each table, `array_style=expand` for one item per line, `spacing=compact` for `key=value`, or disable `keep_comments` when you intentionally want a comment-free file.

## Limits and edge cases

- Input must be valid TOML. Invalid input returns an error and no formatted output.
- `array_style=collapse` cannot preserve comments inside arrays because a single-line array cannot safely contain `#` comments.
- Output uses LF line endings and a trailing newline.
- This is a one-document formatter. For many files, run the CLI command in a shell loop.

## FAQ

<details>
<summary>Does this preserve TOML comments?</summary>

Yes for normal own-line comments and end-of-line comments on entries or table headers. Comments inside arrays are preserved when the array remains expanded; forcing `array_style=collapse` drops those inner comments because they cannot be represented safely on one line.

</details>

<details>
<summary>Will formatting change numeric or string values?</summary>

The parser validates values, but scalar literals are emitted from the syntax tree rather than reconstructed from a generic value model. That means spellings such as `0xFF`, `1_000_000`, date offsets and literal strings are kept instead of being rewritten.

</details>

<details>
<summary>What does the key sorting option sort?</summary>

`sort_keys=asc` and `sort_keys=desc` sort entries within each table and keys inside inline tables. They do not reorder array values because array order is often meaningful in TOML configuration.

</details>

<details>
<summary>Why is the default indent set to zero?</summary>

Most common TOML files, including Cargo.toml and pyproject.toml, keep entries flat under each table header. The default follows that convention; set the indent slider above zero if you prefer nested table entries to be indented.

</details>

## Related tools

- [Validate config files with line and column errors](https://gizza.ai/tools/config-file-validator/): Validate pasted JSON, YAML, TOML, INI or XML config files in your browser with line/column diagnostics, context, hints and JSON reports.
- [Resolve Git merge conflict markers](https://gizza.ai/tools/merge-conflict-resolver/): Paste a file with Git conflict markers and resolve every block by keeping ours, theirs, both sides or the diff3 common ancestor, with per-conflict overrides.
- [Absolute value, sign, or negation for a whole column](https://gizza.ai/tools/absolute-value-transformer/): Paste a column of numbers and apply absolute value, sign extraction (-1/0/1), sign flipping, or force-negative to every value at once, with rounding and an audit table.
- [Adjacency Matrix Converter](https://gizza.ai/tools/adjacency-matrix-converter/): Convert a graph between edge list, adjacency matrix, and incidence matrix — directed or undirected, weighted or not. Free, private, runs in your browser.
- [Amazon Order Analyzer](https://gizza.ai/tools/amazon-order-analyzer/): Paste an Amazon order-history CSV export to summarize total spend by month, top items, and category breakdowns. Browser-only, private, with Markdown or JSON output.