navig-bookmarks

A local bookmark manager: import from any browser or HTML export, full-text search, AI folder plans and tags with your own AI, dead-link checks, duplicate cleanup, and Netscape HTML export with folders.

Works on its own — its own CLI, no navig required · v0.1.0 · not on PyPI yet (install from source below)

On its own (no navig needed)

pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-bookmarks"
navig-bookmarks --help   # no navig needed

With navig

pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-bookmarks"
navig bookmarks --help

A local bookmark manager for the terminal. Dump years of bookmarks from any browser into one searchable store, let your own AI propose a clean folder tree (you see the plan first), find dead links and duplicates, and export the result back to any browser — folders intact.

Runs on its own (navig-bookmarks) or inside navig (navig bookmarks). Same commands, same store.

Quick start

pip install navig-bookmarks

navig-bookmarks import ~/Downloads/bookmarks.html     # or: import --source chrome
navig-bookmarks search python asyncio
navig-bookmarks https://example.com/article            # save one
navig-bookmarks organize                               # AI folder plan, dry run
navig-bookmarks organize --apply --force               # write it (undo file is kept)
navig-bookmarks check                                  # dead links and redirects
navig-bookmarks dedupe --apply                         # merge the same page saved twice
navig-bookmarks export cleaned.html                    # import this into your browser

Commands

Every list command takes --json.

Your AI, your choice

organize and tag --ai use navig's AI setup when navig is installed. Without navig, the first of these that is configured answers:

• NAVIG_AI_BASE_URL + NAVIG_AI_MODEL (+ NAVIG_AI_API_KEY): any OpenAI-compatible server — LM Studio, vLLM, a company gateway, Cloudflare Workers AI's OpenAI-compatible endpoint;
• a provider key: OPENAI_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY, XAI_API_KEY;
• a local Ollama.

--provider / --model pin one for a run (inside navig too). With nothing configured the command says how to set one up and exits 2.

How organize stays safe

• Dry run by default. You see a per-folder diff and sample moves; nothing changes.
• Validated. Every bookmark must get a folder, the AI may not invent ids, folders are at most 3 levels deep. A plan that fails any check is refused (--allow-partial keeps skipped bookmarks where they are).
• Failsafe. A plan that moves more than 20 % of your bookmarks, or makes more than 1 000 changes, needs --force.
• Undo. --apply saves the previous folders first; organize --undo <file> restores them.
• Cheap on big libraries. A site with many bookmarks is sent as one group, batches are sized to stay reliable, and later batches reuse the folders earlier ones created.

Link checks

check asks for headers only (falling back to a GET whose body is never read), follows redirects itself and checks every hop against the SSRF guard, so a bookmark that redirects to a private or cloud-metadata address is reported as blocked, never contacted. At most 8 checks run at once, 2 per site.

Data

One SQLite file: <navig data dir>/bookmarks.db (~/.navig/data/bookmarks.db by default; NAVIG_BOOKMARKS_DB overrides it). Tags remember their source (you, AI, rule) so an AI re-run replaces only AI tags. Nothing is uploaded anywhere except the titles, sites and folders you send to the AI you configured when you run organize or tag --ai.

Licence

MIT. Parts are adapted from linkding (MIT) — see THIRD_PARTY_NOTICES.md.