Back to Details

karakeep

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Karakeep

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是一款开源的自托管书签管理器，用于收集、整理和搜索内容。本技能涵盖核心概念以及如何通过CLI与Karakeep交互。

When to use

适用场景

Use this skill when the user wants to interact with their Karakeep instance (adding bookmarks, managing lists/tags, searching, etc.).
当用户想要与其Karakeep实例交互（添加书签、管理列表/标签、搜索等）时，可使用本技能。

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.
  • 书签：Karakeep中的核心实体，可分为链接、文本或媒体三类。
    • 链接：保存URL——Karakeep会自动抓取标题、描述、图片、截图和全页归档。
    • 文本：作为书签存储的快速笔记或文本片段。
    • 媒体：直接上传的图片和PDF文件。
  • 收藏：为书签添加星标以便快速访问。
  • 归档：将书签从首页隐藏，但仍保持可搜索状态。
  • 备注：为任意书签添加个人上下文笔记。
  • 高亮：阅读时保存引用、摘要或待办事项——可在所有书签中搜索这些内容。

Lists

列表

  • 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.
  • 手动列表：按项目或主题整理的精选集合，可设为私有或公开。
  • 智能列表：由搜索查询驱动的自动更新列表（例如 
    #ai -archived
    ）。
  • 协作：可邀请编辑者（可添加书签）或查看者（只读权限）加入列表。

Tags

标签

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.
用于标记任意书签的轻量级标签（主题、来源、工作流状态等）。每个书签可添加多个标签，标签会随书签在不同列表间同步。配置后AI可自动生成标签。

Search Query Language

搜索查询语言

Karakeep has a powerful search query language for finding the right bookmarks. It supports full-text search, boolean logic, qualifiers, and more.
Karakeep拥有强大的搜索查询语言，用于精准查找书签，支持全文搜索、布尔逻辑、限定词等功能。

Basic Syntax

基础语法

  • 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
    ).
  • 条件之间的空格表示隐式“AND”。
  • 使用 
    and
    / 
    or
    关键字实现显式布尔逻辑。
  • 在任意限定词前添加 
    -
    或 
    !
    表示否定（例如 
    -is:archived
    , 
    !is:fav
    ）。
  • 使用括号 
    ()
    进行分组（注意：分组本身不能被否定）。
  • 不属于限定词的文本将被视为全文搜索（例如 
    machine learning is:fav
    ）。

Qualifiers

限定词

QualifierDescriptionExample
is:fav
Favorited 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: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
限定词描述示例
is:fav
已收藏的书签
is:fav
is:archived
已归档的书签
-is:archived
is:tagged
带有一个或多个标签的书签
is:tagged
is:inlist
属于一个或多个列表的书签
is:inlist
is:link
链接类型书签
is:link
is:text
文本/笔记类型书签
is:text
is:media
媒体类型书签（图片/PDF）
is:media
is:broken
抓取失败或状态码非2xx的书签
is:broken
url:<value>
匹配URL子串
url:github.com
title:<value>
匹配标题子串（支持带引号的字符串）
title:rust
, 
title:"my title"
#<tag>
或 
tag:<tag>
匹配带有指定标签的书签（支持带引号的字符串）
#important
, 
tag:"work in progress"
list:<name>
匹配属于指定列表的书签（支持带引号的字符串）
list:reading
, 
list:"to review"
after:<date>
创建日期为指定日期或之后（格式：YYYY-MM-DD）
after:2024-01-01
before:<date>
创建日期为指定日期或之前（格式：YYYY-MM-DD）
before:2024-12-31
age:<time-range>
按创建时长筛选。使用 
<
/ 
>
指定最大/最小时长。单位：
d
（天）、
w
（周）、
m
（月）、
y
（年）
age:<1d
, 
age:>2w
, 
age:<6m
feed:<name>
从指定RSS源导入的书签
feed:Hackernews
source:<value>
按捕获源匹配。可选值：
api
, 
web
, 
cli
, 
mobile
, 
extension
, 
singlefile
, 
rss
, 
import
source:rss
, 
-source:web

Examples

示例

undefined
undefined

Favorited bookmarks from 2024 tagged "important"

2024年收藏且标记为"important"的书签

is:fav after:2024-01-01 before:2024-12-31 #important
is:fav after:2024-01-01 before:2024-12-31 #important

Archived bookmarks in "reading" list or tagged "work"

已归档且属于"reading"列表或标记为"work"的书签

is:archived and (list:reading or #work)
is:archived and (list:reading or #work)

Untagged or unorganized bookmarks

未标记或未归类的书签

-is:tagged or -is:inlist
-is:tagged or -is:inlist

Recent bookmarks from the last week

最近一周创建的书签

age:<1w
age:<1w

Full-text search combined with qualifiers

结合全文搜索与限定词

machine learning is:fav -is:archived
undefined
machine learning is:fav -is:archived
undefined

RSS Feeds

RSS源

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).
Karakeep不仅可用于订阅RSS源，还可作为RSS源发布器。
  • 发布：将任意列表导出为带唯一令牌的RSS源。
  • 订阅：自动监控外部RSS源，从新内容创建书签（每小时执行，支持重复内容检测）。

Automation

自动化

  • Rule Engine: If-this-then-that rules to auto-tag, favorite, or route bookmarks to lists.
  • Webhooks: Subscribe to bookmark events (add/update/archive).
  • 规则引擎：通过“如果-那么”规则自动为书签添加标签、收藏或归类到指定列表。
  • Webhooks：订阅书签事件（添加/更新/归档）。

Interacting with Karakeep via the CLI

通过CLI与Karakeep交互

Installation

安装

bash
npm install -g @karakeep/cli
Or via Docker:
bash
docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help
bash
npm install -g @karakeep/cli
或通过Docker安装：
bash
docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help

Authentication

身份验证

The CLI requires an API key and server address. Get the API key from your Karakeep instance's settings page.
Option 1 — Environment variables (recommended):
bash
export KARAKEEP_API_KEY="your-api-key"
CLI需要API密钥和服务器地址。可从Karakeep实例的设置页面获取API密钥。
选项1 — 环境变量（推荐）：
bash
export KARAKEEP_API_KEY="your-api-key"

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"

**Option 2 — CLI flags:**

```bash
karakeep --api-key <key> --server-addr <addr> <command>
Verify authentication:
bash
karakeep whoami
export KARAKEEP_SERVER_ADDR="https://cloud.karakeep.com"

**选项2 — CLI参数：**

```bash
karakeep --api-key <key> --server-addr <addr> <command>
验证身份：
bash
karakeep whoami

Bookmark Commands

书签命令

Run 
karakeep --help
to see all available commands, but the most important ones are:
bash
undefined
运行 
karakeep --help
查看所有可用命令，以下是最重要的几个：
bash
undefined

Add a link bookmark

添加链接书签

karakeep bookmarks add --link "https://example.com"
karakeep bookmarks add --link "https://example.com"

Add a link with tags and to a specific list

添加带标签并指定列表的链接

karakeep bookmarks add --link "https://example.com" --tag-name "reading" --list-id <list-id>
karakeep bookmarks add --link "https://example.com" --tag-name "reading" --list-id <list-id>

Add a text bookmark

添加文本书签

karakeep bookmarks add --note "Remember to review the PR"
karakeep bookmarks add --note "Remember to review the PR"

Get bookmark details

获取书签详情

karakeep bookmarks get <bookmark-id> karakeep bookmarks get <bookmark-id> --include-content
karakeep bookmarks get <bookmark-id> karakeep bookmarks get <bookmark-id> --include-content

Update a bookmark

更新书签

karakeep bookmarks update <bookmark-id> --title "New Title" karakeep bookmarks update <bookmark-id> --archive karakeep 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 <bookmark-id> --title "New Title" karakeep bookmarks update <bookmark-id> --archive karakeep bookmarks update <bookmark-id> --favourite karakeep bookmarks update-tags <bookmark-id> --add-tag "important" karakeep bookmarks update-tags <bookmark-id> --remove-tag "old-tag"

List management

列表管理

karakeep lists list karakeep lists get --list <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 lists list karakeep lists get --list <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>

List all bookmarks

列出所有书签

karakeep bookmarks list
karakeep bookmarks list

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
karakeep bookmarks search "is:fav #work" karakeep bookmarks search "rust" --limit 10 --sort-order relevance karakeep bookmarks search "is:tagged" --all # 分页查看所有结果

Delete a bookmark

删除书签

karakeep bookmarks delete <bookmark-id>

You can always pass `--json` to get raw JSON output instead of pretty-printed output.
karakeep bookmarks delete <bookmark-id>

你可以始终添加 `--json` 参数来获取原始JSON输出，而非格式化后的输出。