brew-hop-search

Fast offline-first search of Homebrew formulae, casks, taps, and installed packages.

Built on SQLite + FTS5 for instant local search with smart caching.

Install

# PyPI (recommended)
uv tool install brew-hop-search     # or: pip install brew-hop-search
uvx brew-hop-search python          # one-shot without install

# Homebrew tap
brew tap mcint/brew-hop-search
brew install brew-hop-search

Examples

brew-hop-search python                 # search formulae + casks (top 20)
brew-hop-search -f python build        # multi-word, formulae only
brew-hop-search '^python' '!@3.9'      # anchored + negated terms (see --help=query)
brew-hop-search 'name:^py' d:build     # scoped: name-prefix + desc term
brew-hop-search -c -i                  # casks, installed only
brew-hop-search -i -n0                 # all installed (-n|--limit: N, 0=all, N+offset for paging)
# BREW_HOP_SEARCH_LIMIT=50 in your shell rc overrides the default 20
brew-hop-search -q python | fzf        # pipe to fzf
brew-hop-search --csv python | qsv sort -s name  # sort CSV
brew-hop-search --sql python | sqlite3 results.db  # import to sqlite
brew-hop-search -O                     # show outdated (local)
brew-hop-search -O --brew-verify       # diff: bhs vs brew
brew-hop-search -H python@3.13         # version history for rollback
brew-hop-search --refresh python       # force re-fetch

How it works

On first run, fetches Homebrew formula and cask indexes from formulae.brew.sh into SQLite with FTS5. Subsequent searches are instant (local DB). Caches older than 6 hours trigger a background refresh on the next run; override with --stale=DUR or force immediate with --refresh.

Source	Flag	Data	Calls brew?
Remote API	(default)	`formulae.brew.sh`	No
Installed	`-i`	`brew info --json=v2 --installed`	Yes
Taps	`-t`	`.rb` files in `$(brew --repo)/Library/Taps/`	Yes
Local	`-L`	Brew's API cache at `$(brew --cache)/api/`	Yes
Outdated	`-O`	Compares installed vs API index	No
Outdated	`-O --brew-verify`	Diff bhs vs `brew outdated`	Yes

Example output

Default search — clean, human-optimal:

  # formulae (5/8316)  • brew install python-argcomplete
    python-argcomplete  3.6.3  Tab completion for Python argparse  │ https://kislyuk.github.io/argcomplete/
    python-build  1.4.3  Simple, correct PEP 517 build frontend  │ https://github.com/pypa/build
    python-freethreading  3.14.4  Interpreted, interactive, object-oriented programming language  │ https://www.python.org/
    python-gdbm@3.11  3.11.15  Python interface to gdbm  │ https://www.python.org/
    python-gdbm@3.12  3.12.13  Python interface to gdbm  │ https://www.python.org/
  # casks (5/7629)  • brew install --cask anaconda
    anaconda  2025.12-2  Distribution of the Python and R programming languages for scientific computing  │ https://www.anaconda.com/
    armory  0.96.5  Python-Based Bitcoin Software  │ https://btcarmory.com/
    chia  2.7.0  GUI Python implementation for the Chia blockchain  │ https://www.chia.net/
    drawbot  3.132  Write Python scripts to generate two-dimensional graphics  │ https://www.drawbot.com/
    pycharm-ce  2025.2.5,252.28238.29  IDE for Python programming - Community Edition  │ https://www.jetbrains.com/pycharm/

With -v — source tags and cache info:

  -- cache: 2h59m old   searching formula + cask
  # formulae (5/8316)  • brew install python-argcomplete
  f python-argcomplete  3.6.3  Tab completion for Python argparse  │ https://kislyuk.github.io/argcomplete/
  f python-build  1.4.3  Simple, correct PEP 517 build frontend  │ https://github.com/pypa/build
  f python-freethreading  3.14.4  Interpreted, interactive, object-oriented programming language  │ https://www.python.org/
  f python-gdbm@3.11  3.11.15  Python interface to gdbm  │ https://www.python.org/
  f python-gdbm@3.12  3.12.13  Python interface to gdbm  │ https://www.python.org/
  # casks (5/7629)  • brew install --cask anaconda
  c anaconda  2025.12-2  Distribution of the Python and R programming languages for scientific computing  │ https://www.anaconda.com/
  c armory  0.96.5  Python-Based Bitcoin Software  │ https://btcarmory.com/
  c chia  2.7.0  GUI Python implementation for the Chia blockchain  │ https://www.chia.net/
  c drawbot  3.132  Write Python scripts to generate two-dimensional graphics  │ https://www.drawbot.com/
  c pycharm-ce  2025.2.5,252.28238.29  IDE for Python programming - Community Edition  │ https://www.jetbrains.com/pycharm/

Quiet mode (-q) for piping:

$ brew-hop-search -q python | fzf
python-argcomplete  3.6.3  Tab completion for Python argparse  │ https://kislyuk.github.io/argcomplete/
python-build  1.4.3  Simple, correct PEP 517 build frontend  │ https://github.com/pypa/build
python-freethreading  3.14.4  Interpreted, interactive, object-oriented programming language  │ https://www.python.org/
anaconda  2025.12-2  Distribution of the Python and R programming languages for scientific computing  │ https://www.anaconda.com/
armory  0.96.5  Python-Based Bitcoin Software  │ https://btcarmory.com/
chia  2.7.0  GUI Python implementation for the Chia blockchain  │ https://www.chia.net/

Output formats

CSV (`--csv`)

source,name,version,description,homepage
f,python-argcomplete,3.6.3,Tab completion for Python argparse,https://kislyuk.github.io/argcomplete/
f,python-build,1.4.3,"Simple, correct PEP 517 build frontend",https://github.com/pypa/build
f,python-freethreading,3.14.4,"Interpreted, interactive, object-oriented programming language",https://www.python.org/
c,anaconda,2025.12-2,Distribution of the Python and R programming languages for scientific computing,https://www.anaconda.com/
c,armory,0.96.5,Python-Based Bitcoin Software,https://btcarmory.com/
c,chia,2.7.0,GUI Python implementation for the Chia blockchain,https://www.chia.net/

Table (`--table`)

S  Name                  Ver                    Description                                         Homepage                              
-  --------------------  ---------------------  --------------------------------------------------  --------------------------------------
f  python-argcomplete    3.6.3                  Tab completion for Python argparse                  https://kislyuk.github.io/argcomplete/
f  python-build          1.4.3                  Simple, correct PEP 517 build frontend              https://github.com/pypa/build         
f  python-freethreading  3.14.4                 Interpreted, interactive, object-oriented program…  https://www.python.org/               
f  python-gdbm@3.11      3.11.15                Python interface to gdbm                            https://www.python.org/               
f  python-gdbm@3.12      3.12.13                Python interface to gdbm                            https://www.python.org/               
c  anaconda              2025.12-2              Distribution of the Python and R programming lang…  https://www.anaconda.com/             
c  armory                0.96.5                 Python-Based Bitcoin Software                       https://btcarmory.com/                
c  chia                  2.7.0                  GUI Python implementation for the Chia blockchain   https://www.chia.net/                 
c  drawbot               3.132                  Write Python scripts to generate two-dimensional …  https://www.drawbot.com/              
c  pycharm-ce            2025.2.5,252.28238.29  IDE for Python programming - Community Edition      https://www.jetbrains.com/pycharm/

Also: --tsv, --json (full) / --json=short (compact rows), --sql, -g (grep).

Cache status (`-C`)

  db  brew-hop-search/brew-hop-search.db  61.6 MB
  formula    8316  2h59m ago  fts  30MB json
  cask    7629  2h59m ago  fts  14MB json
  installed:f     460  6m ago
  installed:c      86  6m ago
  taps      50  3d12h ago
  local:f     161  3d12h ago
  local:c      59  3d12h ago

Usage

usage: brew-hop-search [-fcitL] [-VCOH] [-gqT|--json[=MODE]|--csv|--tsv|--sql] [-n N[+OFF]] [--refresh[=DUR]] [query ...]

Fast offline-first Homebrew formula/cask search.

positional arguments:
  query                 search terms (AND-matched)

sources (composable, default: remote API):
  -f, --formulae, --formula
                        formulae only
  -c, --casks, --cask   casks only
  -i, --installed       installed packages
  -t, --taps            tapped repos
  -L, --local           local API cache (offline)

info:
  -h [MODE]             terse help (or MODE: man, <section>, <flag>)
  --help [MODE]         full help (or MODE: man, <section>, <flag>)
  --man                 offline man page (same as --help=man)
  -V, --version         version (-VV: commits + PyPI)
  -C, --cache-status    cache status
  -O, --outdated        outdated packages
  --brew-verify         use brew for -O (slower, authoritative)
  -H, --history         version history for rollback

cache:
  --refresh [DUR]       sync refresh (bare: force, =DUR: if older)
  --stale [DUR]         background refresh threshold (default: 6h)

output:
  -g, --grep            tab-separated for piping
  -q, --quiet           results only (for grep/fzf)
  --json [MODE]         JSON output; MODE=full (default) or short (compact row
                        fields)
  --csv                 CSV output
  --tsv                 tab-separated with header
  -T, --table           aligned columns (like sqlite3 -column)
  --sql                 SQLite INSERT statements
  -n N[+OFF], --limit N[+OFF]
                        max results [+offset], 0=all (default: 20, or
                        $BREW_HOP_SEARCH_LIMIT)
  -v, --verbose         source tags, cache info (-vv per-source detail)

Direct DB access

The SQLite database is at ~/.cache/brew-hop-search/brew-hop-search.db:

sqlite-utils tables ~/.cache/brew-hop-search/brew-hop-search.db
sqlite-utils search ~/.cache/brew-hop-search/brew-hop-search.db formula python

Docs

Design System — cartesian spec architecture
Specs — INPUT, OUTPUT, ENVELOPE, SCHEMA, per-feature
Comparables — Python project references
Least Surprise — operational principles
Man page — full reference

Version

brew-hop-search 0.3.7 (dev+3: 206de5a+dirty)

License

MPL-2.0 — file-level copyleft. Fixes to covered files come back as MPL; new files and downstream projects can pick their own license.

Name		Name	Last commit message	Last commit date
Latest commit History 112 Commits
.beads		.beads
.github/workflows		.github/workflows
Formula		Formula
docs		docs
hooks		hooks
scripts		scripts
src/brew_hop_search		src/brew_hop_search
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.md.template		README.md.template
SECURITY.md		SECURITY.md
brew-search		brew-search
hatch_build.py		hatch_build.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

brew-hop-search

Install

Examples

How it works

Example output

Output formats

CSV (`--csv`)

Table (`--table`)

Cache status (`-C`)

Usage

Direct DB access

Docs

Version

License

About

Uh oh!

Releases 8

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

brew-hop-search

Install

Examples

How it works

Example output

Output formats

CSV (--csv)

Table (--table)

Cache status (-C)

Usage

Direct DB access

Docs

Version

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

CSV (`--csv`)

Table (`--table`)

Cache status (`-C`)

Packages