# htmlq — Like jq but for HTML, Using CSS Selectors

> Extract content from HTML files on the command line using CSS selectors, built in Rust for speed and simplicity.

## Install

Save in your project root:

# htmlq — Like jq but for HTML, Using CSS Selectors

## Quick Use
```bash
cargo install htmlq
# Or: brew install htmlq
curl -s https://example.com | htmlq 'h1'
curl -s https://example.com | htmlq 'a' -a href   # extract link URLs
curl -s https://example.com | htmlq '.main' -t    # text content only
```

## Introduction
htmlq is a command-line tool that lets you extract data from HTML using CSS selectors, the same way jq works for JSON. Written in Rust, it reads HTML from stdin and prints matching elements, attributes, or text to stdout.

## What htmlq Does
- Selects HTML elements using standard CSS selector syntax
- Extracts specific attributes with the `-a` flag (e.g., `-a href` for links)
- Outputs plain text content with `-t`, stripping all HTML tags
- Pipes cleanly with curl, wget, or any command that outputs HTML
- Pretty-prints matched HTML with proper indentation using `-p`

## Architecture Overview
htmlq is a single-binary CLI tool written in Rust. It uses the html5ever parser (the same HTML parser used by Firefox's Servo engine) for spec-compliant DOM construction, and the kuchikiki library for CSS selector matching. The tool reads the entire HTML document into memory, applies the selector, and streams matching nodes to stdout.

## Self-Hosting & Configuration
- Install with `cargo install htmlq` from crates.io
- Available via Homebrew on macOS: `brew install htmlq`
- Available on most Linux distributions via package managers
- No configuration file needed; all options are command-line flags
- Works with piped input only; does not fetch URLs on its own

## Key Features
- CSS3 selector syntax for precise element targeting
- Attribute extraction mode for scraping links, images, or metadata
- Text-only output mode for clean data extraction
- Pretty-print mode for readable HTML output
- Small static binary with no runtime dependencies

## Comparison with Similar Tools
- **pup** — similar HTML selector tool written in Go, supports pseudo-classes
- **xidel** — more powerful with XPath and XQuery, but heavier
- **hq** — Python-based HTML/JSON query tool with jq-like syntax
- **Beautiful Soup** — Python library for HTML parsing, not a CLI tool

## FAQ
**Q:** Can htmlq fetch URLs directly?
A: No. Pipe HTML into it from curl, wget, or a file: `curl -s URL | htmlq 'selector'`.

**Q:** Does it support XPath?
A: No, only CSS selectors. Use xidel if you need XPath support.

**Q:** Can I chain multiple selectors?
A: Yes. Standard CSS combinator syntax works: `htmlq 'div.content > p'`.

**Q:** What license does htmlq use?
A: MIT license.

## Sources
- https://github.com/mgdm/htmlq
- https://crates.io/crates/htmlq

---
Source: https://tokrepo.com/en/workflows/asset-baff9069
Author: AI Open Source