---
name: bookmark
description: Manage a personal reading list. Use when the user wants to save, list, mark as read, or remove article URLs for later reading. Triggers on "bookmark", "save URL", "read later", "reading list", "bookmarks".
---

# Bookmark

Manage a personal reading list stored in SQLite (`db/bookmark.sqlite`).

## Commands

All commands run via:
```bash
/home/nanobot/.local/bin/uv run /home/nanobot/.nanobot/workspace/skills/bookmark/scripts/bookmark.py <command> [args]
```

### Add a bookmark

```bash
bookmark.py add <url> "<description>" [--tags tag1,tag2]
```

- `url` — the article URL
- `description` — short human-readable description (required)
- `--tags` — optional comma-separated tags

Example:
```bash
bookmark.py add "https://example.com/rust-async" "Async Rust patterns" --tags rust,async
```

### List unread bookmarks

```bash
bookmark.py list [--tag <tag>]
```

Shows display ID, URL, tags, description, and date added for each unread bookmark. Use `--tag` to filter (display IDs stay global, so a filtered list may show gaps).

### Display IDs

The `#1`, `#2`, … shown by `list` and `history` are **display IDs** — sequential positions, computed on the fly, never the internal DB id. They renumber whenever the set changes, so run `list`/`history` first if unsure.

- `read <n>` and `show <n>` take the display ID from **`list`** (the unread set).
- `unread <n>` takes the display ID from **`history`** (the read set).

A freshly added bookmark is always display `#1` in `list` (newest first).

### Mark as read

```bash
bookmark.py read <display-id>
```

`<display-id>` is the number from `list`. Marks bookmark as read (stores `read_at` timestamp). Does **not** delete — entry stays in DB.

### Unmark (mark as unread again)

```bash
bookmark.py unread <display-id>
```

`<display-id>` is the number from `history`.

### Show bookmark details

```bash
bookmark.py show <display-id>
```

`<display-id>` is the number from `list`. Shows full URL, description, tags, status, and dates. Does **not** change any state.

### List read bookmarks (history)

```bash
bookmark.py history
```

Shows all bookmarks marked as read, with both `added` and `read` dates, numbered with their own display IDs.

## Output formatting

When presenting bookmark lists or details to the user, **always use markdown links** so URLs are clickable in WebUI and Telegram:

```
#3 [hackaday.com](https://hackaday.com/2026/06/02/linux-fu-taming-strace/) [linux, strace] — lepší strace
```

Format: `#<display-id> [<domain>](<url>) [<tags>] — <description>`

- Domain is clickable, pointing to the full URL
- Tags in brackets, comma-separated
- Description after em-dash
- **Never** strip URLs from the output or replace them with plain-text summaries

## Workflow

1. User shares a URL → `add` with description and optional tags
2. User wants to see what to read → `list`
3. User wants to see details of a bookmark → `show <display-id>` (from `list`)
4. User finishes an article → `read <display-id>` (from `list`)
5. User wants to revisit → `unread <display-id>` (from `history`) or `history`