Bunnify

A Python bookmark manager and URL shortcut system: terminal CLI, web command palette, Chrome OpenSearch integration, and parameterized redirects.

Install

pipx is the recommended path for end users:

pipx install bunnify
pipx ensurepath   # adds ~/.local/bin to PATH if needed (restart the shell)
bunnify --version
bunnify onboard   # print bookmarks / setup / Chrome next steps

pipx installs bunnify and bunnify-server under ~/.local/bin by default (or $PIPX_BIN_DIR when set). Ensure that directory is on your PATH before running either command. Prefer the pipx apps over any checkout ./scripts/bunnify still on PATH.

The wheel installs bunnify (CLI) and bunnify-server (Django server). No repository checkout or uv is required at runtime.

Package on PyPI: pypi.org/project/bunnify.

After install or upgrade

pipx does not print package docs after install. Run:

bunnify onboard

That prints the ready-to-go checklist (bookmarks path, bunnify setup, Chrome/Edge, and upgrade). Same text:

bunnify --onboard

Summary of what it covers:

1. Bookmarks at ~/.config/bunnify/bookmarks.json (required before the server starts) — bunnify setup can install the example shortcuts, or seed from bunnify.json.example
2. bunnify setup — local on a laptop; remote for a home/always-on host
   LOCAL.md
3. Chrome / Edge — match BUNNIFY_BASE_URL from config.env
   CHROME_SETUP.md
4. Try it: bunnify gh or address-bar keyword (e.g. b gh)

Upgrade

Preferred:

bunnify upgrade

That prints the version/commit you are running from, the PyPI target, then the pipx app version/commit to after pipx upgrade. Use this instead of bare pipx upgrade bunnify so you can see when PATH is still a git checkout.

pipx upgrade only updates ~/.local/bin/bunnify. If bunnify --version still shows a checkout SHA, PATH is hitting ./scripts/bunnify or a repo .venv. After pipx ensurepath, command -v bunnify should be ~/.local/bin/bunnify.

Bookmarks and ~/.config/bunnify/config.env are user data — upgrades do not overwrite them. After a major server change, re-run bunnify setup only if docs or release notes say so. Setup will offer to stop a different local Bunnify build and start this CLI's build when the port is already in use.

Source and docs: github.com/the-hcma/bunnify.

Quick start

1. Bookmarks file

bunnify setup offers to install the example bookmarks when none exist yet. You can also create the file yourself from the documented example into XDG config:

mkdir -p ~/.config/bunnify
curl -fsSL https://raw.githubusercontent.com/the-hcma/bunnify/main/bunnify.json.example \
  -o ~/.config/bunnify/bookmarks.json
# edit ~/.config/bunnify/bookmarks.json with your shortcuts

See Configuration for overrides (BUNNIFY_BOOKMARKS, XDG_CONFIG_HOME).

2. Configure local or remote mode

bunnify setup

Laptop / daily machine: choose local (default). Setup starts a managed server, verifies /health, records the port, and saves settings to ~/.config/bunnify/config.env. Point Chrome or Edge at the same BUNNIFY_BASE_URL (Chrome / Edge setup).

Home server / always-on host: choose remote on client devices and enter that host’s URL. Prefer a centralized remote install when several machines share one server — not as a laptop’s only dependency if you often go offline.

One-time override without saving: bunnify --base-url https://… shortcut.

Details: Local and remote setup.

3. Run shortcuts

bunnify              # interactive REPL (Tab completion, history)
bunnify gh           # open a shortcut in the browser
bunnify bun          # Bunnify source on GitHub
bunnify pr the-hcma/bunnify 272   # parameterized shortcut
bunnify --fzf        # fuzzy picker
bunnify --print-url gh

Unknown keys exit non-zero in direct mode (no search-engine fallback).

Features

• CLI / REPL — fuzzy Tab completion, fzf mode, Vim/Emacs edit keys
• Web — /cmd/ command palette, /list/ browser, smart /search/
• Chrome / Edge — OpenSearch at /opensearch.xml (setup guide)
• Parameters — URLs with #{name} placeholders and optional defaults
• Validation — JSON Schema on load; reserved keys h / help

Server lifecycle

Installed users manage the server with bunnify-server:

bunnify-server --help
# Foreground (systemd, LaunchAgent, debugging):
bunnify-server --foreground --noninteractive --port 8000
# Background managed daemon (returns after fork):
bunnify-server --port 8000 --noninteractive --pid-dir ~/.local/share/bunnify/run
bunnify-server --stop --pid-dir ~/.local/share/bunnify/run
curl --max-time 2 http://127.0.0.1:8000/health

bunnify setup starts a managed local server for daily CLI use. Stop it with:

bunnify stop

That prints the URL and runtime directory before stopping. Details: Local and remote setup.

Linux production: systemd user service via setup-service from repository-helpers.

macOS: LaunchAgent example.

Web usage

With the server running (default http://127.0.0.1:8000 after setup):

Bookmarks format

{
  "gh": {
    "description": "GitHub",
    "url": "https://github.com/"
  },
  "pr": {
    "description": "Pull request",
    "url": "https://github.com/#{repo}/pull/#{pr_number}",
    "defaults": { "repo": "org/repo" }
  }
}

Required fields: description, url. Placeholders use #{parameter_name}. Reload after edits: the server watches the JSON file, or run load_bookmarks in a development checkout.

Development checkout

Contributors clone the repo and use uv — separate from the pipx path above.

git clone https://github.com/the-hcma/bunnify.git
cd bunnify
uv sync
uv run python manage.py migrate

mkdir -p ~/.config/bunnify
cp bunnify.json.example ~/.config/bunnify/bookmarks.json

./scripts/bunnify setup
./scripts/bunnify-server --console --log-level DEBUG   # optional
./test_bunnify

Full guidelines: CONTRIBUTING.md. Quality gates: ./scripts/checks.

Wrappers under ./scripts/ prefer uv run when uv is on PATH, otherwise the checkout .venv (same entry points systemd uses on service hosts).

Documentation

Troubleshooting

Server won't start

bunnify-server --console --log-level DEBUG
# or in a checkout: ./scripts/bunnify-server --console

Bookmarks missing

ls -l ~/.config/bunnify/bookmarks.json
# run `bunnify setup` (offers the example), or copy bunnify.json.example

CLI can't reach server

bunnify setup
curl -sf "$(grep BUNNIFY_BASE_URL ~/.config/bunnify/config.env | cut -d= -f2-)/health"

Stale managed process

bunnify-server --stop --pid-dir ~/.local/share/bunnify/run

Releasing

Maintainers: docs/RELEASING.md (Release Please + PyPI).

License

MIT — see LICENSE.