karakeep

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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
```
）。
协作：可邀请编辑者（可添加书签）或查看者（只读权限）加入列表。

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

限定词

Qualifier	Description	Example
`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

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

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

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

Untagged or unorganized bookmarks

未标记或未归类的书签

-is:tagged or -is:inlist

Recent bookmarks from the last week

最近一周创建的书签

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"

Add a link with tags and to a specific list

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

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"

Get bookmark details

获取书签详情

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"

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>

List all bookmarks

列出所有书签

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输出，而非格式化后的输出。

karakeep

Original

Translation

Karakeep

Karakeep

When to use

适用场景

Core Concepts

核心概念

Bookmarks

书签

Lists

列表

Tags

标签

Search Query Language

搜索查询语言

Basic Syntax

基础语法

Qualifiers

限定词

Examples

示例

Favorited bookmarks from 2024 tagged "important"

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

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

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

Untagged or unorganized bookmarks

未标记或未归类的书签

Recent bookmarks from the last week

最近一周创建的书签

Full-text search combined with qualifiers

结合全文搜索与限定词

RSS Feeds

RSS源

Automation

自动化

Interacting with Karakeep via the CLI

通过CLI与Karakeep交互

Installation

安装

Authentication

身份验证

If self-hosted, pass the server address as well. It defaults to the cloud instance if not set:

如果是自托管实例，还需传入服务器地址。未设置时默认使用云端实例：

Bookmark Commands

书签命令

Add a link bookmark

添加链接书签

Add a link with tags and to a specific list

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

Add a text bookmark

添加文本书签

Get bookmark details

获取书签详情

Update a bookmark

更新书签

List management

列表管理

List all bookmarks

列出所有书签

Search bookmarks

搜索书签

Delete a bookmark

删除书签