Metadata-Version: 2.4
Name: navig-bookmarks
Version: 0.1.0
Summary: 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.
Author: navig
License: MIT
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,plugin,bookmarks,netscape,browser,organize,dead-links,dedupe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.17.0
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.7.0
Dynamic: license-file

# navig-bookmarks

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> 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)

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

**With navig**

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

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig bookmarks add` | Save a bookmark. |
| `navig bookmarks check` | Find dead links and redirects (headers only; private addresses are never contacted). |
| `navig bookmarks dedupe` | Find bookmarks that point at the same page (tracking parameters, www., http/https ignored). |
| `navig bookmarks delete` | Delete a bookmark. |
| `navig bookmarks edit` | Change a bookmark. |
| `navig bookmarks export` | Export bookmarks as Netscape HTML (with folders) or JSON. |
| `navig bookmarks folders` | Folders and how many bookmarks each holds. |
| `navig bookmarks import` | Import bookmarks — folders are kept; URLs already saved are skipped. |
| `navig bookmarks list` | List bookmarks, most recently used first. |
| `navig bookmarks migrate` | Copy bookmarks from navig's old `links` store (also done automatically; safe to repeat). |
| `navig bookmarks open` | Open a bookmark. With a vault credential and navig installed, the login is filled in. |
| `navig bookmarks organize` | Plan a clean folder tree with your AI. Dry run unless --apply. |
| `navig bookmarks rules add` | Add a rule (applies to new bookmarks; run `rules apply` for existing ones). |
| `navig bookmarks rules apply` | Re-tag every bookmark from the current rules (only rule tags are replaced). |
| `navig bookmarks rules list` | List tagging rules. |
| `navig bookmarks rules remove` | Remove a rule (its tags stay until `rules apply`). |
| `navig bookmarks search` | Full-text search. |
| `navig bookmarks show` | Everything about one bookmark. |
| `navig bookmarks tag` | Add or remove tags — or let the AI tag (it only ever replaces its own tags). |
| `navig bookmarks tags` | Tags and how often each is used. |
| `navig bookmarks version` | Print the plugin version. |

</details>

<!-- navig:plugin-card:end -->

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

```bash
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

| Command | What it does |
|---|---|
| `add <url>` (or just `<url>`) | Save a bookmark: `--title`, `--notes`, `--tags a,b`, `--folder "Dev/Python"`, `--cred`. |
| `list` / `search <words>` / `show <id>` | Browse, full-text search (title, URL, notes, tags, folder), details. |
| `open <id>` | Open in the browser; with a vault credential and navig installed, the login is filled in. |
| `edit <id>` / `delete <id>` | Change or remove one. |
| `tag <id> <tag>...` / `tag --ai` | Add tags yourself, or let the AI tag (`--untagged`, `--all`, `--curated`, `--dry-run`). |
| `import [file]` | Netscape HTML, JSON, Chrome/Edge `Bookmarks`, Firefox `places.sqlite`, Safari `Bookmarks.plist`. |
| `export [file]` | Netscape HTML with nested folders (default) or `--format json`. |
| `organize` | AI folder plan. `--apply`, `--force`, `--export plan.html`, `--folder`, `--limit`, `--undo <file>`. |
| `check` | Dead links, redirects, archived copies of dead pages. `--fail-on-dead` for scripts. |
| `dedupe` | Same page saved more than once; `--apply` merges. |
| `rules list/add/remove/apply` | Offline `domain/path -> tags` rules, applied on add and import. |
| `folders` / `tags` | What you have. |
| `migrate` | Copy bookmarks from navig's old `links` store (also automatic). |

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](https://github.com/sissbruecker/linkding) (MIT) — see
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
