Query TOML configuration files with the Tq terminal utility

The tq program lets you query TOML configuration files with a sequence of intuitive filters. It works as a regular Unix filter program reading input data from the standard input and producing results to the standard output. Consult the package documentation or check the Usage section to see how you can use tq.

Installation

Install the program and use tq on the command-line to filter TOML files on the terminal.

go install github.com/mdm-code/tq/cmd/tq@latest

Here is how you can get the whole Go package downloaded to fiddle with, but it does not expose any public interfaces in code.

go get github.com/mdm-code/tq

Usage

Enter tq -h to get usage information and the list of options that can be used with the command. Here is table with the supported filter expressions and some examples to get you going on how to use tq in your workflow.

Supported filters

Filter	Expression
identity	.
key	["string"]
index	[0]
iterator	[]
span	[:]

Retrieve IPs from a table of server tables

In the example below, the TOML input file is (1) queried with the key ["servers"], then (2) the retrieved table is converted to an iterator of objects with [], and then (3) the IP address is recovered from each of the objects with the key ["ip"].

tq -q '["servers"][]["ip"]' <<EOF
[servers]

[servers.prod]
ip = "10.0.0.1"
role = "backend"

[servers.staging]
ip = "10.0.0.2"
role = "backend"
EOF

Output:

'10.0.0.1'
'10.0.0.2'

Retrieve selected ports from a list of databases

This example queries the TOML input for the for the all ports aside from the first one assigned to the first database record on the list.

tq -q '.["databases"][0]["ports"][1:][]' <<EOF
databases = [ {enabled = true, ports = [ 5432, 5433, 5434 ]} ]
EOF

Output:

5433
5434

Run inside of a container

If you don't feel like installing tq with go install, you can test tq out running inside of a container with this command:

docker run -i ghcr.io/mdm-code/tq:latest tq -q "['dependencies']['ignore']" <<EOF
[dependencies]
anyhow = "1.0.75"
bstr = "1.7.0"
grep = { version = "0.3.1", path = "crates/grep" }
ignore = { version = "0.4.22", path = "crates/ignore" }
lexopt = "0.3.0"
log = "0.4.5"
serde_json = "1.0.23"
termcolor = "1.1.0"
textwrap = { version = "0.16.0", default-features = false }
EOF

Development

Go through the Makefile to get an idea of the formatting, testing and linting that can be used locally for development purposes. Remember to install golint before you try to run tests and test the build or installation:

go install golang.org/x/lint/golint@latest

License

Copyright (c) 2024 Michał Adamczyk.

This project is licensed under the MIT license. See LICENSE for more details.