TOML

TOML for configuration files — simpler than YAML, no indentation footguns.

Tables and Keys

Standard table — maps to a JSON object

[server]
hostname = "modestus-aw"
port = 8080
enabled = true

Dotted keys — inline nesting without a table header

server.hostname = "modestus-aw"
server.port = 8080

Nested tables — multi-level hierarchy

[server.tls]
cert = "/etc/ssl/certs/server.crt"
key = "/etc/ssl/private/server.key"
protocols = ["TLSv1.2", "TLSv1.3"]

Inline table — compact single-line object for simple structures

database = { host = "localhost", port = 5432, name = "appdb" }

Arrays of Tables

Array of tables with [[double brackets]] — maps to a JSON array of objects

[[interfaces]]
name = "eth0"
vlan = 10
ip = "10.50.1.100"

[[interfaces]]
name = "eth1"
vlan = 20
ip = "10.50.2.100"

Nested array of tables — interfaces with multiple addresses

[[interfaces]]
name = "eth0"

[[interfaces.addresses]]
ip = "10.50.1.100"
prefix = 24

[[interfaces.addresses]]
ip = "10.50.1.101"
prefix = 24

String Types

Basic string — supports escape sequences like \n and \t

path = "C:\\Users\\evan\\config"
greeting = "Hello\nWorld"

Literal string — single quotes, no escape processing

regex = '^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$'
winpath = 'C:\Users\evan\config'

Multi-line basic string — triple quotes, line ending backslash trims whitespace

description = """
This is a long description \
that spans multiple lines \
but joins into one."""

Multi-line literal string — preserves all whitespace and newlines

script = '''
#!/bin/bash
set -euo pipefail
echo "Hello from TOML"
'''

Data Types

Integers, floats, booleans, datetimes — TOML is strongly typed

vlan_id = 10
mtu = 9_000              # underscores for readability
uptime_percent = 99.95
enabled = true

created = 2026-04-10T08:00:00Z           # RFC 3339 datetime
date_only = 2026-04-10                    # local date
time_only = 08:00:00                      # local time

Reading TOML

Read a TOML value with taplo — built-in TOML toolkit

taplo get -f config.toml "server.hostname"

Format/lint a TOML file — fix indentation and ordering

taplo fmt config.toml

Check TOML syntax without modifying — returns exit code 1 on errors

taplo check config.toml

Read TOML in Python — stdlib tomllib (Python 3.11+)

python3 -c "
import tomllib, json, sys
with open('config.toml', 'rb') as f:
    data = tomllib.load(f)
print(json.dumps(data, indent=2, default=str))
"

Read a specific TOML key in Python — extract a nested value

python3 -c "
import tomllib
with open('pyproject.toml', 'rb') as f:
    data = tomllib.load(f)
print(data['project']['name'])
"

Read TOML with yq — yq v4.30+ supports TOML input

yq -p=toml '.server.hostname' config.toml

Convert TOML to JSON — pipe through yq for jq processing

yq -p=toml -o=json config.toml | jq '.server'

Cargo.toml Patterns

Inspect Cargo.toml dependencies — extract dependency names and versions

yq -p=toml -o=json Cargo.toml | jq -r '.dependencies | to_entries[] | "\(.key) = \(.value)"'

Check if a specific dependency exists

yq -p=toml '.dependencies.serde' Cargo.toml

pyproject.toml Patterns

Extract project metadata from pyproject.toml

yq -p=toml -o=json pyproject.toml | jq '{name: .project.name, version: .project.version, requires_python: .project.requires_python}'

List all project dependencies

yq -p=toml -o=json pyproject.toml | jq -r '.project.dependencies[]'

List dev dependencies (poetry-style)

yq -p=toml -o=json pyproject.toml | jq -r '.tool.poetry.group.dev.dependencies | keys[]'

Sorting and Validation

Sort TOML keys alphabetically — consistent diffs in version control

toml-sort config.toml -i

Sort with trailing newline — avoids git diff noise

toml-sort config.toml -i --trailing-comma-inline-array

Diff two TOML files as JSON — compare content regardless of key order

diff <(yq -p=toml -o=json file1.toml | jq -S .) \
     <(yq -p=toml -o=json file2.toml | jq -S .)