tq: A Standalone TOML Query CLI
tq extracts a value from a TOML file using a simple dotted or bracketed path selector, printing it as raw text, JSON, or TOML.
Where tomlq wraps jq, the standalone tq (the Rust cortex/tomlq-style tool) uses a lightweight path syntax and no jq dependency, which keeps CI images small.
What it does
tq reads a TOML file (via -f or stdin), walks the path you provide such as package.version or dependencies["serde"], and prints the selected value. Output format is controlled by -o (raw text, json, or toml).
Common usage
tq -f Cargo.toml package.version
cat pyproject.toml | tq 'tool.poetry.name'
# JSON output for a whole table
tq -f Cargo.toml -o json dependenciesOptions
| Flag | What it does |
|---|---|
| -f <file> | Read TOML from a file instead of stdin |
| -o <format> | Output format: raw text, json, or toml |
| -r | Raw output for string scalars |
| <path> | Dotted/bracketed selector, e.g. a.b["c"] |
In CI
tq is a good fit when you only need one value and do not want to install a jq-based stack. It ships as a single binary, so a runner can fetch it and read a version in one step. Confirm which tq is on the image, since the name is shared by more than one project.
Common errors in CI
A missing key prints an error like "key not found" or an empty result depending on the build; treat an empty value as a failure in scripts. A malformed file yields a TOML parse error naming the line. If the installed tq expects -f but you piped on stdin (or vice versa), it reports a usage error, so match the invocation to the binary you have.