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

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for mcint from gravatar.com mcint

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License Expression: MPL-2.0
    SPDX License Expression
  • Author: mcint
  • Tags brew , cli , homebrew , macos , search
  • Requires: Python >=3.9
Classifiers
Report project as malware

Project description

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.

GitHub · PyPI · Brew Tap

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

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.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for mcint from gravatar.com mcint

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License Expression: MPL-2.0
    SPDX License Expression
  • Author: mcint
  • Tags brew , cli , homebrew , macos , search
  • Requires: Python >=3.9
Classifiers

Release history Release notifications | RSS feed

This version

0.3.7

0.3.6

0.3.5

0.3.4

0.3.2

0.3.1

0.3.0

0.2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

brew_hop_search-0.3.7.tar.gz (679.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

brew_hop_search-0.3.7-py3-none-any.whl (64.5 kB view details)

Uploaded Python 3

File details

Details for the file brew_hop_search-0.3.7.tar.gz.

File metadata

  • Download URL: brew_hop_search-0.3.7.tar.gz
  • Upload date:
  • Size: 679.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for brew_hop_search-0.3.7.tar.gz
Algorithm Hash digest
SHA256 acbef0b125c0455d19f2cf52fc4dec078f50799e1f1b509b33ce4b4af060421a
MD5 3fce8570ed121dc0639a5a1cc2f92ff6
BLAKE2b-256 e8a5a27daf274e98ecdd53dabc1c43e3e7d3bca7ceaf62f8163aceb692c27419

See more details on using hashes here.

File details

Details for the file brew_hop_search-0.3.7-py3-none-any.whl.

File metadata

  • Download URL: brew_hop_search-0.3.7-py3-none-any.whl
  • Upload date:
  • Size: 64.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for brew_hop_search-0.3.7-py3-none-any.whl
Algorithm Hash digest
SHA256 c21bde635e96bf7c7ed2d25cd9b8fae93131d5d6ca8307f9d134645c31213390
MD5 a031137615286bb2850982240c624598
BLAKE2b-256 18b5db0c29644f21bacd529c72adf53a70196d3300494af2e7731c103655d41d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page