karakeep

Karakeep

Karakeep は、リンク、メモ、画像、PDF を収集、整理、検索するためのオープンソースのブックマークマネージャーです。このスキルを使うと、公式 CLI を通じて Karakeep インスタンスを操作できます。

使用するタイミング

ユーザーから Karakeep のコンテンツの追加、取得、検索、整理、エクスポート、またはその他の管理を依頼された場合に、このスキルを使用してください。

HTTP リクエストを直接記述するよりも、CLI を優先してください。ここで説明されていないコマンドを使う場合は、karakeep --help または karakeep <command> --help を実行してください。karakeep skill は、インストール済み CLI に同梱されたスキルを出力します。このスキルは、別途インストールされたコピーより新しい場合があります。

主な概念

Karakeep では、次の 3 種類のブックマークを保存します。

• リンク。Karakeep は、ページのタイトル、説明、画像、スクリーンショット、読みやすいコンテンツ、ページ全体のアーカイブを取得できます。
• テキスト。ブックマークとして保存されるメモやテキストのスニペットです。
• アセット。ブックマークとしてアップロードされる画像や PDF です。

ブックマークには、タグ、メモ、ハイライト、お気に入りやアーカイブの状態を設定でき、1 つ以上のリストに追加できます。手動リストには選択したブックマークが含まれます。スマートリストでは保存済みの検索クエリが使用され、一致するブックマークの変更に応じて更新されます。

すでに存在するリンクを保存しても、重複は作成されません。CLI を含む通常の保存では、Karakeep は既存のブックマークをアーカイブから復元して先頭に移動します。呼び出し元から指定されていないメタデータは変更されません。

Karakeep では、RSS フィードを取り込んだり、リストを RSS フィードとして公開したりできます。ルールエンジンでは、新しいブックマークにタグを付けたり、お気に入りにしたり、リストに振り分けたりできます。Webhook はブックマークのイベントを通知します。

検索クエリ言語

条件間のスペースは and を意味します。明示的なブール論理を指定するには、and、or、かっこを使用します。修飾子の前に - または ! を付けると否定になります。修飾子の一部でないテキストは検索テキストになります。

修飾子	意味	例
is:fav	お気に入りのブックマーク	is:fav
is:archived	アーカイブ済みのブックマーク	-is:archived
is:tagged	1 つ以上のタグが付いたブックマーク	-is:tagged
is:inlist	1 つ以上のリストに含まれるブックマーク	is:inlist
has:notes	空でないメモがあるブックマーク	has:notes
has:highlights	1 つ以上のハイライトがあるブックマーク	-has:highlights
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:"release notes"
#<tag> または tag:<tag>	タグ名	#important、tag:"in progress"
list:<name>	リスト名	list:"to review"
after:<date>	YYYY-MM-DD 以降に作成	after:2026-01-01
before:<date>	YYYY-MM-DD 以前に作成	before:2026-06-01
age:<range>	d、w、m、y を使った作成からの経過期間	age:<1w、age:>6m
feed:<name>	ソース RSS フィード	feed:Hackernews
source:<value>	取り込み元	source:cli、-source:rss

有効な取り込み元は、api、web、cli、mobile、extension、singlefile、rss、import です。

例：

is:fav after:2026-01-01 #important
is:archived and (list:reading or #work)
-is:tagged or -is:inlist
has:notes -has:highlights
machine learning is:fav -is:archived

CLI のインストール

npm install -g @karakeep/cli

コンテナイメージも利用できます。

docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help

認証

Karakeep の設定ページで API キーを作成します。永続的に使用する最も簡単な設定方法は次のとおりです。

karakeep auth init
karakeep whoami

auth init はサーバーアドレスと API キーの入力を求めます。$XDG_CONFIG_HOME/karakeep/config.json に、または XDG_CONFIG_HOME が設定されていない場合は ~/.config/karakeep/config.json に、モード 0600 の JSON ファイルを書き込みます。既存のファイルを変更する前に確認を求めます。確認なしで上書きするには --force を使用します。

非対話型で設定する場合は、グローバルオプションを auth init の前に指定します。

karakeep --server-addr "https://karakeep.example.com" --api-key "$KARAKEEP_API_KEY" auth init --force

CLI は次の順序で認証情報を解決します。

1. グローバルコマンドオプションの --api-key と --server-addr。
2. KARAKEEP_API_KEY と KARAKEEP_SERVER_ADDR 環境変数。
3. 永続設定ファイル。

サーバーアドレスのデフォルトは https://cloud.karakeep.app です。API キーにデフォルト値はありません。保存済みの設定を変更せずに一度だけ実行するコマンドでは、グローバルオプションを使用します。

karakeep --api-key <key> --server-addr <addr> whoami

ブックマークの追加とインポート

# 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"

元の URL を指定して SingleFile HTML アーカイブをインポートします。

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 には skip、overwrite、overwrite-recrawl、append、または append-recrawl を指定できます。デフォルトは skip です。recrawl を含む値を指定すると、アーカイブの保存後にクロールがキューに追加されます。

ブックマークの検索

bookmarks search は次の 3 つのモードに対応しています。

• fts はデフォルトの全文検索です。
• semantic はブックマークの埋め込み表現を検索します。検索テキストが空でないこと、埋め込みプロバイダーとベクトルストアプロバイダーが設定されていることが必要です。類似度のしきい値を下回る結果は除外されるため、指定した上限より少ない件数が返される場合があります。
• hybrid は全文検索とセマンティック検索のランキングを組み合わせます。クエリが修飾子のみで構成されている場合、またはセマンティック検索の基盤を利用できない場合は、全文検索にフォールバックします。

セマンティック検索とハイブリッド検索では、セマンティックランキングが実行される場合にのみ関連度順の並べ替えがサポートされます。また、インスタンスでセマンティック検索と自動埋め込みインデックス作成が有効になっている必要があります。

# Full-text search with qualifiers.
karakeep bookmarks search "rust is:fav" --limit 10

# 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

検索言語を必要としない構造化フィルターには bookmarks list を使用します。

karakeep bookmarks list --list-id <list-id> --include-archived
karakeep bookmarks list --tag-id <tag-id> --all

--all を指定しない場合、list コマンドと search コマンドは次のページがあるとカーソルを出力します。--cursor <cursor> でそのカーソルを渡してください。

コンテンツの読み取りとアセットのダウンロード

bookmarks get でブックマークのメタデータを取得します。--include-content を指定すると、保存済みのコンテンツが結果に含まれます。

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

長いコンテンツには、範囲を指定できる読み取り可能なコンテンツ取得コマンドを使用します。Markdown またはプレーンテキストを返し、続きがある場合は継続カーソルを出力します。

karakeep bookmarks content <bookmark-id> --format markdown --max-chars 20000
karakeep bookmarks content <bookmark-id> --cursor <cursor>

チャンクサイズの上限は 50,000 Unicode 文字です。bookmarks get で表示されるアセット ID を指定して、添付ファイルまたはアセットをダウンロードします。

karakeep assets download <asset-id> --output ./download.pdf
karakeep assets download <asset-id> --output ./download.pdf --force

ブックマークの更新と整理

karakeep bookmarks update <bookmark-id> --title "New title" --description "New description"
karakeep bookmarks update <bookmark-id> --archive
karakeep bookmarks update <bookmark-id> --no-archive
karakeep bookmarks update <bookmark-id> --favourite
karakeep bookmarks update-tags <bookmark-id> --add-tag important --remove-tag inbox

karakeep lists list
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 tags list
karakeep tags get --name important
karakeep tags merge --into <target-tag-id> --from <tag-id> <tag-id>

karakeep highlights list --bookmark <bookmark-id>
karakeep highlights get <highlight-id>

ブックマーク、リスト、タグ、ハイライトを削除するコマンドを利用できます。使用する前に、対象をユーザーに確認してください。

機械可読な出力

結果を別のプログラムまたはエージェントが使用する場合は、グローバルオプションの --json を使用します。解釈が曖昧にならないよう、コマンドの前に指定してください。

karakeep --json bookmarks search "#work" --all
karakeep --json whoami