htmlq: Extract Text and Attributes From HTML
htmlq reads HTML on stdin and applies a CSS selector, printing matching elements, their text with --text, or an attribute with --attribute.
When a CI check needs a value off a rendered page or a static HTML report, htmlq is jq for HTML: a CSS selector in, the matched content out. This page covers the pipeline usage; the base reference is htmlq-css-select-html.
What it does
htmlq parses HTML from stdin, selects nodes matching a CSS selector, and prints them. --text extracts just the text content, --attribute <name> pulls a specific attribute value, and -p pretty-prints the matched HTML. It pairs with curl to scrape a page.
Common usage
curl -s https://example.com | htmlq --text 'h1'
curl -s https://example.com | htmlq --attribute href 'a.download'
# extract every link
curl -s https://example.com | htmlq --attribute href aOptions
| Flag | What it does |
|---|---|
| --text, -t | Print the text content of matched elements |
| --attribute <name> | Print the value of the named attribute |
| -p, --pretty | Pretty-print the matched HTML |
| -b <url>, --base | Rewrite relative URLs against a base |
| -w, --remove-nodes <sel> | Remove matching nodes before output |
In CI
htmlq is the reliable way to pull a version string or a download URL from a release page: curl -s <url> | htmlq --attribute href a.latest. A selector that matches nothing prints an empty string and exits 0, so a step that must find a value should test that the output is non-empty and fail otherwise.
Common errors in CI
htmlq returns empty output (not an error) when the selector matches nothing, so guard with [ -n "$out" ] to fail on a missing element. "Invalid selector" or a parse error is printed for a malformed CSS selector; check pseudo-classes htmlq supports. Because it parses static HTML, content injected by JavaScript is absent, which reads as an unexpectedly empty match.