A self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search
feat(skill): improve skills to mention new features
Mohamed Bassem08d5963b23d6
diff --git a/skills/SKILL.md b/skills/SKILL.mdindex c07fa7bb..c99baa64 100644--- a/skills/SKILL.md+++ b/skills/SKILL.md@@ -6,15 +6,13 @@ metadata:openclaw:envVars:- name: KARAKEEP_API_KEY- required: true- description: The API key for your Karakeep instance+ required: false+ description: Optional API key override. The CLI can also read it from its config file.- name: KARAKEEP_SERVER_ADDRrequired: false- description: The server address for your Karakeep instance.+ description: Optional server override. The CLI can also read it from its config file.+ primaryEnv: KARAKEEP_API_KEYrequires:- env:- - KARAKEEP_API_KEY- - KARAKEEP_SERVER_ADDRbins:- karakeephomepage: https://karakeep.app@@ -31,181 +29,217 @@ metadata:# Karakeep-Karakeep is an open source self-hosted bookmark manager for collecting, organizing, and searching content. This skill covers the core concepts and how to interact with Karakeep via the CLI.+Karakeep is an open source bookmark manager for collecting, organizing, and searching links, notes, images, and PDFs. Use this skill to operate a Karakeep instance through the official CLI.## When to use-Use this skill when the user wants to interact with their Karakeep instance (adding bookmarks, managing lists/tags, searching, etc.).--## Core Concepts--### Bookmarks--- **Bookmarks**: Core entity in Karakeep. Can be one of links, text or media.- - **Links**: Save URLs — Karakeep auto-fetches title, description, image, screenshot, and full-page archive.- - **Text**: Quick notes or text snippets stored as bookmarks.- - **Media**: Images and PDFs uploaded directly.-- **Favorites**: Star bookmarks for quick access.-- **Archiving**: Hide bookmarks from the homepage while keeping them searchable.-- **Notes**: Attach personal context notes to any bookmark.-- **Highlights**: Save quotes, summaries, or TODOs while reading — searchable across all bookmarks.+Use this skill when the user asks to add, retrieve, search, organize, export, or otherwise manage content in Karakeep.-### Lists+Prefer the CLI over writing direct HTTP requests. Run `karakeep --help` or `karakeep <command> --help` when a command is not covered here. `karakeep skill` prints the skill bundled with the installed CLI, which may be newer than a separately installed copy.-- **Manual lists**: Curated collections organized by project or topic. Can be private or public.-- **Smart lists**: Auto-updating lists powered by search queries (e.g., `#ai -archived`).-- **Collaboration**: Invite editors (can add bookmarks) or viewers (read-only) to a list.+## Core concepts-### Tags+Karakeep stores three bookmark types:-Lightweight labels for any bookmark (topics, sources, workflow states). Multiple tags per bookmark, tags travel with bookmarks across lists. AI can auto-generate tags when configured.+- Links. Karakeep can fetch the page title, description, image, screenshot, readable content, and full-page archive.+- Text. Notes and text snippets stored as bookmarks.+- Assets. Images and PDFs uploaded as bookmarks.-### Search Query Language+Bookmarks can have tags, notes, highlights, favorite and archive state, and membership in one or more lists. Manual lists contain selected bookmarks. Smart lists use a saved search query and update as matching bookmarks change.-Karakeep has a powerful search query language for finding the right bookmarks. It supports full-text search, boolean logic, qualifiers, and more.+Saving a link that already exists does not create a duplicate. For ordinary saves, including the CLI, Karakeep restores the existing bookmark from the archive and moves it to the top. Metadata that the caller did not supply remains unchanged.-#### Basic Syntax+Karakeep can consume RSS feeds and publish lists as RSS feeds. Its rule engine can tag, favorite, or route new bookmarks to lists. Webhooks report bookmark events.-- Spaces between conditions act as implicit AND.-- Use `and` / `or` keywords for explicit boolean logic.-- Prefix any qualifier with `-` or `!` to negate it (e.g., `-is:archived`, `!is:fav`).-- Use parentheses `()` for grouping (note: groups themselves can't be negated).-- Any text not part of a qualifier is treated as full-text search (e.g., `machine learning is:fav`).+## Search query language-#### Qualifiers+Spaces between conditions mean `and`. Use `and`, `or`, and parentheses for explicit boolean logic. Prefix a qualifier with `-` or `!` to negate it. Text that is not part of a qualifier becomes the search text.-| Qualifier | Description | Example |-|-----------|-------------|---------|-| `is:fav` | Favorited bookmarks | `is:fav` |+| Qualifier | Meaning | Example |+| --- | --- | --- |+| `is:fav` | Favorite bookmarks | `is:fav` || `is:archived` | Archived bookmarks | `-is:archived` |-| `is:tagged` | Bookmarks with one or more tags | `is:tagged` |-| `is:inlist` | Bookmarks in one or more lists | `is:inlist` |+| `is:tagged` | Bookmarks with at least one tag | `-is:tagged` |+| `is:inlist` | Bookmarks in at least one list | `is:inlist` || `is:link` | Link bookmarks | `is:link` |-| `is:text` | Text/note bookmarks | `is:text` |-| `is:media` | Media bookmarks (images/PDFs) | `is:media` |-| `is:broken` | Bookmarks with failed crawls or non-2xx status codes | `is:broken` |-| `url:<value>` | Match URL substring | `url:github.com` |-| `title:<value>` | Match title substring (supports quoted strings) | `title:rust`, `title:"my title"` |-| `#<tag>` or `tag:<tag>` | Match bookmarks with specific tag (supports quoted strings) | `#important`, `tag:"work in progress"` |-| `list:<name>` | Match bookmarks in a specific list (supports quoted strings) | `list:reading`, `list:"to review"` |-| `after:<date>` | Created on or after date (YYYY-MM-DD) | `after:2024-01-01` |-| `before:<date>` | Created on or before date (YYYY-MM-DD) | `before:2024-12-31` |-| `age:<time-range>` | Filter by creation age. Use `<` / `>` for max/min age. Units: `d` (days), `w` (weeks), `m` (months), `y` (years) | `age:<1d`, `age:>2w`, `age:<6m` |-| `feed:<name>` | Bookmarks imported from a specific RSS feed | `feed:Hackernews` |-| `source:<value>` | Match by capture source. Values: `api`, `web`, `cli`, `mobile`, `extension`, `singlefile`, `rss`, `import` | `source:rss`, `-source:web` |--#### Examples+| `is:text` | Text bookmarks | `is:text` |+| `is:media` | Image or PDF bookmarks | `is:media` |+| `is:broken` | Failed crawls or non-2xx responses | `is:broken` |+| `url:<value>` | URL substring | `url:github.com` |+| `title:<value>` | Title substring | `title:"release notes"` |+| `#<tag>` or `tag:<tag>` | Tag name | `#important`, `tag:"in progress"` |+| `list:<name>` | List name | `list:"to review"` |+| `after:<date>` | Created on or after `YYYY-MM-DD` | `after:2026-01-01` |+| `before:<date>` | Created on or before `YYYY-MM-DD` | `before:2026-06-01` |+| `age:<range>` | Creation age using `d`, `w`, `m`, or `y` | `age:<1w`, `age:>6m` |+| `feed:<name>` | Source RSS feed | `feed:Hackernews` |+| `source:<value>` | Capture source | `source:cli`, `-source:rss` |++Valid capture sources are `api`, `web`, `cli`, `mobile`, `extension`, `singlefile`, `rss`, and `import`.++Examples:++```text+is:fav after:2026-01-01 #important+is:archived and (list:reading or #work)+-is:tagged or -is:inlist+machine learning is:fav -is:archived+```++## Install the CLI+```bash+npm install -g @karakeep/cli```-# Favorited bookmarks from 2024 tagged "important"-is:fav after:2024-01-01 before:2024-12-31 #important-# Archived bookmarks in "reading" list or tagged "work"-is:archived and (list:reading or #work)+The container image is also available:-# Untagged or unorganized bookmarks--is:tagged or -is:inlist+```bash+docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help+```-# Recent bookmarks from the last week-age:<1w+## Authenticate-# Full-text search combined with qualifiers-machine learning is:fav -is:archived+Create an API key in the Karakeep settings page. The simplest persistent setup is:++```bash+karakeep auth init+karakeep whoami```-### RSS Feeds+`auth init` prompts for the server address and API key. It writes a mode `0600` JSON file to `$XDG_CONFIG_HOME/karakeep/config.json`, or `~/.config/karakeep/config.json` when `XDG_CONFIG_HOME` is unset. It asks before changing an existing file. Use `--force` to overwrite it without confirmation.-Karakeep can also be used to consume RSS feeds, but also can itself act as an RSS feed publisher.-- **Publishing**: Export any list as an RSS feed with a unique token.-- **Consuming**: Auto-monitor external RSS feeds and create bookmarks from new items (hourly, with duplicate detection).+For non-interactive setup, put the global options before `auth init`:-### Automation+```bash+karakeep --server-addr "https://karakeep.example.com" --api-key "$KARAKEEP_API_KEY" auth init --force+```-- **Rule Engine**: If-this-then-that rules to auto-tag, favorite, or route bookmarks to lists.-- **Webhooks**: Subscribe to bookmark events (add/update/archive).+The CLI resolves credentials in this order:-## Interacting with Karakeep via the CLI+1. Global command options, `--api-key` and `--server-addr`.+2. `KARAKEEP_API_KEY` and `KARAKEEP_SERVER_ADDR` environment variables.+3. The persistent config file.-### Installation+The server address defaults to `https://cloud.karakeep.app`. The API key has no default. Use global options for a one-off command without changing saved config:```bash-npm install -g @karakeep/cli+karakeep --api-key <key> --server-addr <addr> whoami```-Or via Docker:+## Add and import bookmarks```bash-docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help+# Add one or more links. Repeat --link for multiple URLs.+karakeep bookmarks add --link "https://example.com"++# Add tags and list membership while saving.+karakeep bookmarks add --link "https://example.com" --tag-name reading --tag-name work --list-id <list-id>++# Add text directly or from stdin.+karakeep bookmarks add --note "Review the proposal" --title "Reminder"+printf '%s\n' "Long note" | karakeep bookmarks add --stdin++# Upload an image or PDF as an asset bookmark.+karakeep bookmarks add --asset ./paper.pdf --title "Research paper"```-### Authentication+Import a SingleFile HTML archive with its original URL:++```bash+karakeep bookmarks import-singlefile ./page.html --url "https://example.com/page"+karakeep bookmarks import-singlefile ./page.html --url "https://example.com/page" --if-exists overwrite-recrawl+```++`--if-exists` accepts `skip`, `overwrite`, `overwrite-recrawl`, `append`, or `append-recrawl`. The default is `skip`. The `recrawl` variants queue a crawl after storing the archive.++## Find bookmarks++`bookmarks search` supports three modes:-The CLI requires an API key and server address. Get the API key from your Karakeep instance's settings page.+- `fts` is the default full-text search.+- `semantic` searches bookmark embeddings. It requires non-empty search text and configured embedding and vector-store providers. Results below the similarity threshold are omitted, so it may return fewer than the requested limit.+- `hybrid` combines full-text and semantic rankings. It falls back to full-text search when the query contains only qualifiers or semantic infrastructure is unavailable.-**Option 1 — Environment variables (recommended):**+Semantic and hybrid searches support relevance sorting only when semantic ranking runs. The instance must also enable semantic search and automatic embedding indexing.```bash-export KARAKEEP_API_KEY="your-api-key"+# Full-text search with qualifiers.+karakeep bookmarks search "rust is:fav" --limit 10-# If self-hosted, pass the server address as well. It defaults to the cloud instance if not set:-export KARAKEEP_SERVER_ADDR="https://cloud.karakeep.com"+# Find conceptually related content even when wording differs.+karakeep bookmarks search "durable background jobs" --search-mode semantic++# Combine keyword and semantic ranking.+karakeep bookmarks search "rust async patterns #programming" --search-mode hybrid++# Include stored content and fetch every result page.+karakeep bookmarks search "incident review" --include-content --all```-**Option 2 — CLI flags:**+Use `bookmarks list` for structured filters that do not need the search language:```bash-karakeep --api-key <key> --server-addr <addr> <command>+karakeep bookmarks list --list-id <list-id> --include-archived+karakeep bookmarks list --tag-id <tag-id> --all```-**Verify authentication:**+Without `--all`, list and search commands print a cursor when another page exists. Pass it back with `--cursor <cursor>`.++## Read content and download assets++Get bookmark metadata with `bookmarks get`. `--include-content` includes stored content in the result.```bash-karakeep whoami+karakeep bookmarks get <bookmark-id>+karakeep bookmarks get <bookmark-id> --include-content```-### Bookmark Commands--Run `karakeep --help` to see all available commands, but the most important ones are:+For long content, use the bounded readable-content command. It returns Markdown or plain text and prints a continuation cursor when more content remains.```bash-# Add a link bookmark-karakeep bookmarks add --link "https://example.com"+karakeep bookmarks content <bookmark-id> --format markdown --max-chars 20000+karakeep bookmarks content <bookmark-id> --cursor <cursor>+```-# Add a link with tags and to a specific list-karakeep bookmarks add --link "https://example.com" --tag-name "reading" --list-id <list-id>+The maximum chunk size is 50,000 Unicode characters. Download an attachment or asset by the asset ID shown by `bookmarks get`:-# Add a text bookmark-karakeep bookmarks add --note "Remember to review the PR"+```bash+karakeep assets download <asset-id> --output ./download.pdf+karakeep assets download <asset-id> --output ./download.pdf --force+```-# Get bookmark details-karakeep bookmarks get <bookmark-id>-karakeep bookmarks get <bookmark-id> --include-content+## Update and organize bookmarks-# Update a bookmark-karakeep bookmarks update <bookmark-id> --title "New Title"+```bash+karakeep bookmarks update <bookmark-id> --title "New title" --description "New description"karakeep bookmarks update <bookmark-id> --archive+karakeep bookmarks update <bookmark-id> --no-archivekarakeep bookmarks update <bookmark-id> --favourite-karakeep bookmarks update-tags <bookmark-id> --add-tag "important"-karakeep bookmarks update-tags <bookmark-id> --remove-tag "old-tag"+karakeep bookmarks update-tags <bookmark-id> --add-tag important --remove-tag inbox-# List managementkarakeep lists list-karakeep lists get --list <list-id>+karakeep lists create --name "Reading" --icon "📚"+karakeep lists create --name "Recent AI" --icon "🤖" --type smart --query "#ai age:<1m"+karakeep lists get <list-id>karakeep lists add-bookmark --list <list-id> --bookmark <bookmark-id>karakeep lists remove-bookmark --list <list-id> --bookmark <bookmark-id>-karakeep lists delete <list-id>+karakeep tags list+karakeep tags get --name important+karakeep tags merge --into <target-tag-id> --from <tag-id> <tag-id>-# List all bookmarks-karakeep bookmarks list+karakeep highlights list --bookmark <bookmark-id>+karakeep highlights get <highlight-id>+```-# Search bookmarks-karakeep bookmarks search "is:fav #work"-karakeep bookmarks search "rust" --limit 10 --sort-order relevance-karakeep bookmarks search "is:tagged" --all # paginate through all results+Delete commands are available for bookmarks, lists, tags, and highlights. Confirm the target with the user before using them.-# Delete a bookmark-karakeep bookmarks delete <bookmark-id>-```+## Machine-readable output-You can always pass `--json` to get raw JSON output instead of pretty-printed output.+Use the global `--json` option when another program or agent will consume the result. Put it before the command to avoid ambiguity:++```bash+karakeep --json bookmarks search "#work" --all+karakeep --json whoami+```