4 releases (breaking)

0.4.0 Jan 3, 2022
0.3.0 Sep 15, 2021
0.2.0 Sep 11, 2021
0.1.0 May 20, 2019

#1221 in Command line utilities

Download history 73/week @ 2024-01-08 104/week @ 2024-01-15 96/week @ 2024-01-22 167/week @ 2024-01-29 113/week @ 2024-02-05 152/week @ 2024-02-12 138/week @ 2024-02-19 139/week @ 2024-02-26 147/week @ 2024-03-04 121/week @ 2024-03-11 126/week @ 2024-03-18 94/week @ 2024-03-25 140/week @ 2024-04-01 114/week @ 2024-04-08 115/week @ 2024-04-15 101/week @ 2024-04-22

484 downloads per month

MIT license

438 lines


Like jq, but for HTML. Uses CSS selectors to extract bits of content from HTML files.



cargo install htmlq


brew install htmlq


$ htmlq -h
htmlq 0.4.0
Michael Maclean <michael@mgdm.net>
Runs CSS selectors on HTML

    htmlq [FLAGS] [OPTIONS] [--] [selector]...

    -B, --detect-base          Try to detect the base URL from the <base> tag in the document. If not found, default to
                               the value of --base, if supplied
    -h, --help                 Prints help information
    -w, --ignore-whitespace    When printing text nodes, ignore those that consist entirely of whitespace
    -p, --pretty               Pretty-print the serialised output
    -t, --text                 Output only the contents of text nodes inside selected elements
    -V, --version              Prints version information

    -a, --attribute <attribute>         Only return this attribute (if present) from selected elements
    -b, --base <base>                   Use this URL as the base for links
    -f, --filename <FILE>               The input file. Defaults to stdin
    -o, --output <FILE>                 The output file. Defaults to stdout
    -r, --remove-nodes <SELECTOR>...    Remove nodes matching this expression before output. May be specified multiple

    <selector>...    The CSS expression to select [default: html]


Using with cURL to find part of a page by ID

$ curl --silent https://www.rust-lang.org/ | htmlq '#get-help'
<div class="four columns mt3 mt0-l" id="get-help">
        <h4>Get help!</h4>
          <li><a href="https://doc.rust-lang.org">Documentation</a></li>
          <li><a href="https://users.rust-lang.org">Ask a Question on the Users Forum</a></li>
          <li><a href="http://ping.rust-lang.org">Check Website Status</a></li>
        <div class="languages">
            <label class="hidden" for="language-footer">Language</label>
            <select id="language-footer">
                <option title="English (US)" value="en-US">English (en-US)</option>
<option title="French" value="fr">Français (fr)</option>
<option title="German" value="de">Deutsch (de)</option>

$ curl --silent https://www.rust-lang.org/ | htmlq --attribute href a

Get the text content of a post

$ curl --silent https://nixos.org/nixos/about.html | htmlq  --text .main

          About NixOS

NixOS is a GNU/Linux distribution that aims to
improve the state of the art in system configuration management.  In
existing distributions, actions such as upgrades are dangerous:
upgrading a package can cause other packages to break, upgrading an
entire system is much less reliable than reinstalling from scratch,
you can’t safely test what the results of a configuration change will
be, you cannot easily undo changes to the system, and so on.  We want
to change that.  NixOS has many innovative features:


Remove a node before output

There's a big SVG image in this page that I don't need, so here's how to remove it.

$ curl --silent https://nixos.org/ | ./target/debug/htmlq '.whynix' --remove-nodes svg
<ul class="whynix">

          Nix builds packages in isolation from each other. This ensures that they
          are reproducible and don't have undeclared dependencies, so <strong>if a
            package works on one machine, it will also work on another</strong>.

          Nix makes it <strong>trivial to share development and build
            environments</strong> for your projects, regardless of what programming
          languages and tools you’re using.

          Nix ensures that installing or upgrading one package <strong>cannot
            break other packages</strong>. It allows you to <strong>roll back to
            previous versions</strong>, and ensures that no package is in an
          inconsistent state during an upgrade.

Pretty print HTML

(This is a bit of a work in progress)

$ curl --silent https://mgdm.net | htmlq --pretty '#posts'
<section id="posts">
  <h2>I write about...
  <ul class="post-list">
      <time datetime="2019-04-29 00:%i:1556496000" pubdate="">
        29/04/2019</time><a href="/weblog/nettop/">
        <h3>Debugging network connections on macOS with nettop
      <p>Using nettop to find out what network connections a program is trying to make.

Syntax highlighting with bat

$ curl --silent example.com | htmlq 'body' | bat --language html
Syntax highlighted output


~154K SLoC