Buku

buku is a lightweight, self‑hosted bookmark manager that combines a command‑line interface with an optional web server (bukuserver) for browsing. At its core, it exposes a simple SQLite database that can be edited through any text editor or via the CLI. The application is written in Python 3 and leverages a minimal set of dependencies (primarily requests for HTTP fetching, beautifulsoup4 for parsing, and click/argparse for the CLI). This makes it trivial to ship in a single executable or container image, and the database can be version‑controlled (e.g., with Git) for mergeability across machines.

Architecture & Technical Stack

• Language: Python 3.10+ (pure CPython, no compiled extensions)
• Frameworks: click for command‑line parsing; a tiny Flask‑like microservice (bukuserver) built on aiohttp for the web UI
• Database: SQLite (file‑based, ACID compliant) with optional encryption via sqlcipher if desired
• Storage: All bookmarks are stored as rows with fields for URL, title, tags (comma‑separated), description, and metadata such as creation time
• Networking: requests (synchronous) or aiohttp (async) for fetching titles, tags, and checking link health; optional integration with the Wayback Machine API
• Extensibility: The CLI exposes a plugin hook (buku.plugins) that allows developers to write custom commands in pure Python; the web server supports WebSocket notifications for real‑time updates

Core Capabilities & APIs

• Command‑line CRUD: buku add, buku edit, buku rm, buku list with advanced search options (regex, fuzzy, tag filters)
• Import/Export: buku import supports JSON and HTML (XOXO, Netscape) formats; buku export writes to those formats
• Metadata enrichment: On adding a URL, buku automatically fetches the page title, meta description, and OpenGraph tags
• Health checks: buku check can ping URLs or query the Wayback Machine for archived copies
• Web API: bukuserver exposes a RESTful JSON endpoint (/api/bookmarks) and WebSocket channel for push notifications; authentication can be added via HTTP Basic or JWT
• Scripting hooks: Developers can register pre‑ and post‑add callbacks to integrate with CI pipelines or external services

Deployment & Infrastructure

buku is designed for single‑user or small team deployments. It runs natively on Linux, macOS, and Windows (via WSL or native Python). For containerization, a Docker image is available that mounts the SQLite database as a volume; the web server can be exposed on any port, and TLS termination is typically handled by an external reverse proxy (Traefik, Caddy). Scaling horizontally is not a primary goal—each instance maintains its own database—but developers can synchronize databases via Git or rsync to achieve a distributed setup.

Integration & Extensibility

The plugin system is intentionally lightweight: any Python module placed in the buku.plugins package is auto‑discovered and registered as a subcommand. This allows developers to build custom tools—e.g., a bulk import from a CSV, or integration with a password manager to auto‑populate URLs. The web API can be consumed by third‑party dashboards, mobile apps, or browser extensions (the official buku extension for Firefox/Chrome). Webhooks are supported via a simple HTTP POST endpoint that triggers on bookmark events, enabling CI/CD pipelines to react to new bookmarks.

Developer Experience

Documentation is hosted on ReadTheDocs and includes a comprehensive man page, operational notes, and API reference. The codebase follows PEP 8, is heavily commented, and tests cover 90% of the core logic. Community support is active on GitHub Discussions and the project's mailing list, with contributors frequently adding new import formats or improving performance. Licensing under GPLv3 ensures that any derivative work remains open source, which is attractive for developers building internal tooling.

Use Cases

• Personal knowledge base: Store research URLs, annotate them in a local editor, and browse via bukuserver
• Team bookmark sharing: Share a SQLite database over Git or a shared network drive, and use the web UI for quick access
• CI integration: Hook buku add into a build script to automatically archive URLs that trigger tests
• Minimal web service: Deploy bukuserver behind a corporate proxy to provide a lightweight bookmark portal without external dependencies

Advantages Over Alternatives

• Zero‑config, self‑hosted: No external database or service required; the entire state lives in a single file
• Privacy‑first: No telemetry, no external analytics; the application can run offline after initial setup
• Extensibility: Python plugins and a REST API allow developers to integrate buku into almost any workflow
• Performance: SQLite queries are fast for the typical bookmark set size (thousands of entries); the CLI is responsive even on low‑end hardware
• **Open