{"id":37110323,"url":"https://github.com/mdm-code/tq","last_synced_at":"2026-01-14T13:06:04.357Z","repository":{"id":218594608,"uuid":"688608615","full_name":"mdm-code/tq","owner":"mdm-code","description":"Query TOML configuration files with the Tq terminal utility.","archived":false,"fork":false,"pushed_at":"2025-05-06T18:23:40.000Z","size":229,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-06T19:41:36.670Z","etag":null,"topics":["cli","formatter","golang","jq","query","terminal","toml","toml-language","toml-query","tq","unix","v2","yq"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/mdm-code/tq/v2","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mdm-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-09-07T17:53:21.000Z","updated_at":"2025-05-06T18:23:41.000Z","dependencies_parsed_at":"2024-02-13T23:24:22.209Z","dependency_job_id":"34a724a7-79d1-4b58-8939-b11b73cce0c1","html_url":"https://github.com/mdm-code/tq","commit_stats":null,"previous_names":["mdm-code/tq"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/mdm-code/tq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdm-code%2Ftq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdm-code%2Ftq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdm-code%2Ftq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdm-code%2Ftq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mdm-code","download_url":"https://codeload.github.com/mdm-code/tq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdm-code%2Ftq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28420817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","formatter","golang","jq","query","terminal","toml","toml-language","toml-query","tq","unix","v2","yq"],"created_at":"2026-01-14T13:06:02.843Z","updated_at":"2026-01-14T13:06:04.347Z","avatar_url":"https://github.com/mdm-code.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cdiv \u003e\n    \u003cimg\n      src=\"https://raw.githubusercontent.com/mdm-code/mdm-code.github.io/main/tq_logo.png\"\n      alt=\"logo\"\n      style=\"object-fit: contain\"\n      width=\"30%\"\n    /\u003e\n  \u003c/div\u003e\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003eQuery TOML configuration files with the Tq terminal utility\u003c/h4\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cp\u003e\n    \u003ca href=\"https://github.com/mdm-code/tq/actions?query=workflow%3ACI\"\u003e\n        \u003cimg alt=\"Build status\" src=\"https://github.com/mdm-code/tq/workflows/CI/badge.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://app.codecov.io/gh/mdm-code/tq\"\u003e\n        \u003cimg alt=\"Code coverage\" src=\"https://codecov.io/gh/mdm-code/tq/branch/main/graphs/badge.svg?branch=main\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://opensource.org/licenses/MIT\" rel=\"nofollow\"\u003e\n        \u003cimg alt=\"MIT license\" src=\"https://img.shields.io/github/license/mdm-code/tq\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/mdm-code/tq/v2\"\u003e\n        \u003cimg alt=\"Go report card\" src=\"https://goreportcard.com/badge/github.com/mdm-code/tq/v2\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pkg.go.dev/github.com/mdm-code/tq/v2\"\u003e\n        \u003cimg alt=\"Go package docs\" src=\"https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\nThe `tq` program lets you query TOML configuration files with a sequence of\nintuitive filters. It works as a regular Unix filter program reading input data\nfrom the standard input and producing results to the standard output. Consult the\n[package documentation](https://pkg.go.dev/github.com/mdm-code/tq/v2) or check the\n[Usage](#usage) section to see how you can use `tq`.\n\n\n## Installation\n\nInstall the program and use `tq` on the command-line to filter TOML files on\nthe terminal.\n\n```sh\ngo install github.com/mdm-code/tq/v2/cmd/tq@latest\n```\n\nHere is how you can get the whole Go package downloaded to fiddle with, but\nit exposes only the public interfaces for `tq` and the TOML adapter so that\nthe latter can be swapped out.\n\n```sh\ngo get github.com/mdm-code/tq/v2\n```\n\n\n## Usage\n\nEnter `tq -h` to get usage information and the list of options that can be used\nwith the command. Here is table with the supported filter expressions and some\nexamples to get you going on how to use `tq` in your workflow.\n\nSome effort has been made to make queries less clunky to type out on the\ncommand line and the syntax for queries more aligned with the TOML syntax and\nsemantics. It's been decided to drop the requirement for square brackets for\nselectors and quotation marks for bare strings. Queries can now span across\nmultiple lines so that they are still legible as their complexity increases.\nLonger queries run in a shell script might benefit for it. As for quoted\nstrings, both inverted commas and quotes can be used. A note of caution though\nthat these should be used such that they do not interfere with shell quoting.\n\n\n### Supported filters\n\n| \u003ca href=\"#supported-filters\"\u003e\u003cimg width=\"1000\" height=\"0\"\u003e\u003c/a\u003e\u003cp\u003eFilter\u003c/p\u003e | \u003ca href=\"#supported-filters\"\u003e\u003cimg width=\"1000\" height=\"0\"\u003e\u003c/a\u003e\u003cp\u003eExpression\u003c/p\u003e                     |\n| :-------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------: |\n| \u003ckbd\u003e\u003cb\u003eidentity\u003c/b\u003e\u003c/kbd\u003e                                                  | \u003ckbd\u003e\u003cb\u003e.\u003c/b\u003e\u003c/kbd\u003e                                                                                 |\n| \u003ckbd\u003e\u003cb\u003ekey\u003c/b\u003e\u003c/kbd\u003e                                                       | \u003ckbd\u003e\u003cb\u003e[\"string\"]\u003c/b\u003e\u003c/kbd\u003e or \u003ckbd\u003e\u003cb\u003e\"quoted string\"\u003c/b\u003e\u003c/kbd\u003e or \u003ckbd\u003e\u003cb\u003ebare-string\u003c/b\u003e\u003c/kbd\u003e  |\n| \u003ckbd\u003e\u003cb\u003eindex\u003c/b\u003e\u003c/kbd\u003e                                                     | \u003ckbd\u003e\u003cb\u003e[0]\u003c/b\u003e\u003c/kbd\u003e                                                                               |\n| \u003ckbd\u003e\u003cb\u003eiterator\u003c/b\u003e\u003c/kbd\u003e                                                  | \u003ckbd\u003e\u003cb\u003e[]\u003c/b\u003e\u003c/kbd\u003e                                                                                |\n| \u003ckbd\u003e\u003cb\u003espan\u003c/b\u003e\u003c/kbd\u003e                                                      | \u003ckbd\u003e\u003cb\u003e[:]\u003c/b\u003e\u003c/kbd\u003e                                                                               |\n\n\n### Supported escape sequences for quoted strings\n\nCommonly found characters are mapped onto often used escaped sequences. These\ncan be used in quoted strings mostly the same way one would use them in a TOML\nfile though the specification for the TOML language advises against the use of\nfunky keys unless there is a good reason to use them.\n\n```txt\n\\b          - backspace\n\\t          - tab\n\\n          - linefeed\n\\f          - form feed\n\\r          - carriage return\n\\\"          - double quote\n\\'          - single quote\n\\\\          - backslash\n\\uhhhh      - short 16-bit hexadecimal form\n\\Uhhhhhhhh  - long 32-bit hexadecimal form\n```\n\n\n### Conversion caveats\n\nGiven the current implementation, *most* values are represented exactly the way\nthey are spelled out in the input file after they're queried for. The following\nvalue notations will be converted to a different notation related to the\nbacking Go type:\n\n```txt\n1_000       =\u003e 1000   # Underscores are not retained.\n0xFFFF      =\u003e 65535  # Hexadecimal is converted to decimal.\n0o755       =\u003e 493    # Octal is converted to decimal.\n0b1111_1111 =\u003e 255    # Binary is converted to decimal.\n+100        =\u003e 100    # The plus sign is dropped.\n5e-3        =\u003e 0.005  # The exponential notation is not kept.\n\n# Other relevant notations like date, time, date-time, with and without the\n# offset, inf, nan, negative numbers, stay the way they're written in the\n# input file.\n```\n\n\n### Multiline query with bare strings\n\nHere is a dummy configuration file in TOML found on the web for Gitlab\nconnected to a Kubernetes. The file attempts to configure some Gitlab runners.\nThe file is (1) queried with the key `runners` to access the table that is then\n(2) converted to an iterator with `[]`. Then (3) the query goes for\n`kubernetes`, `volumes`, and `host_path` in this order to (4) turn the last one\nto an iterator with `[]`, and then (5) query each element of the iterator for\n`\"host path\"`. Mind the quoted string with the space.\n\n\n```sh\n\u003c\u003c EOF tq -q '\n    .runners[]\n        .kubernetes\n        .volumes\n        .host_path[]\n            .\"host path\"\n'\n[session_server]\n  session_timeout = 1800\n\n[[runners]]\n  name = \"\"\n  url = \"\"\n  token = \"\"\n  executor = \"kubernetes\"\n  cache_dir = \"/tmp/gitlab/cache\"\n  [runners.kubernetes]\n    host = \"\"\n    bearer_token_overwrite_allowed = false\n    image = \"\"\n    namespace = \"\"\n    namespace_overwrite_allowed = \"\"\n    privileged = false\n    memory_limit = \"1Gi\"\n    service_account_overwrite_allowed = \"\"\n    pod_annotations_overwrite_allowed = \"\"\n    [runners.kubernetes.node_selector]\n      gitlab = \"true\"\n    [runners.kubernetes.volumes]\n      [[runners.kubernetes.volumes.host_path]]\n        name = \"gitlab-cache\"\n        mount_path = \"/tmp/gitlab/cache\"\n        \"host path\" = \"/home/core/data/gitlab-runner/data\"\n\n[[runners]]\n  name = \"runner-gitlab-runner-xxx-xxx\"\n  url = \"https://gitlab.com/\"\n  token = \"\u003cmy-token\u003e\"\n  executor = \"kubernetes\"\n  [runners.cache]\n    [runners.cache.s3]\n    [runners.cache.gcs]\n  [runners.kubernetes]\n    host = \"\"\n    bearer_token_overwrite_allowed = false\n    image = \"ubuntu:16.04\"\n    namespace = \"gitlab-managed-apps\"\n    namespace_overwrite_allowed = \"\"\n    privileged = true\n    service_account_overwrite_allowed = \"\"\n    pod_annotations_overwrite_allowed = \"\"\n    [runners.kubernetes.volumes]\nEOF\n```\n\n```txt\nOutput:\n\n/home/core/data/gitlab-runner/data\n```\n\n\n### Retrieve IPs from a table of server tables\n\nIn the example below, the TOML input file is (1) queried with the key\n`servers`, then (2) the retrieved table is converted to an iterator of objects\nwith `[]`, and then (3) the IP address is recovered from each of the objects\nwith the quoted key `\"ip\"`.\n\n```sh\n\u003c\u003cEOF tq -q '.servers[].\"ip\"'\n[servers]\n\n[servers.prod]\nip = \"10.0.0.1\"\nrole = \"backend\"\n\n[servers.staging]\nip = \"10.0.0.2\"\nrole = \"backend\"\nEOF\n```\n\n```txt\nOutput:\n\n10.0.0.1\n10.0.0.2\n```\n\n\n### Retrieve selected ports from a list of databases\n\nThis example uses the older syntax and queries the TOML input for the for the\nall ports aside from the first one assigned to the first database record on the\nlist.\n\n```sh\n\u003c\u003cEOF tq -q '.[\"databases\"][0][\"ports\"][1:][]'\ndatabases = [ {enabled = true, ports = [ 5432, 5433, 5434 ]} ]\nEOF\n```\n\n```txt\nOutput:\n\n5433\n5434\n```\n\n\n### Run inside of a container\n\nIf you don't feel like installing `tq` with `go install`, you can test `tq` out\nrunning inside of a container with this command:\n\n```sh\n\u003c\u003cEOF docker run -i ghcr.io/mdm-code/tq:latest tq -q \".dependencies.ignore\"\n[dependencies]\nanyhow = \"1.0.75\"\nbstr = \"1.7.0\"\ngrep = { version = \"0.3.1\", path = \"crates/grep\" }\nignore = { version = \"0.4.22\", path = \"crates/ignore\" }\nlexopt = \"0.3.0\"\nlog = \"0.4.5\"\nserde_json = \"1.0.23\"\ntermcolor = \"1.1.0\"\ntextwrap = { version = \"0.16.0\", default-features = false }\nEOF\n```\n\n```txt\nOutput:\n\npath = 'crates/ignore'\nversion = '0.4.22'\n```\n\n\n## Development\n\nGo through the [Makefile](Makefile) to get an idea of the formatting, testing\nand linting that can be used locally for development purposes.\n\n\n## License\n\nCopyright (c) 2025 Michał Adamczyk.\n\nThis project is licensed under the [MIT license](https://opensource.org/licenses/MIT).\nSee [LICENSE](LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdm-code%2Ftq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdm-code%2Ftq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdm-code%2Ftq/lists"}