Linkly AI CLI の使い方

Linkly AI CLI の紹介

Linkly AI CLI は、Linkly AI Desktop の MCP サービスに接続して、ターミナルからローカルドキュメントを検索、閲覧、読み取りできるコマンドラインツールです。同時に、AI Agent（Claude Desktop、Cursor など）と Linkly AI の間のブリッジとしても機能します。

ターミナル検索

コマンドラインから直接ドキュメントを検索。開発者やギークユーザーに最適です

MCP ブリッジ

stdio MCP モードで実行し、Claude Desktop、Cursor などの AI ツールから Linkly AI を呼び出せます

インストール

macOS / Linux
Windows
Cargo

ターミナルで以下を実行：

curl -sSL https://updater.linkly.ai/cli/install.sh | sh

または Homebrew でインストール：

brew tap LinklyAI/tap
brew install linkly

PowerShell で以下を実行：

irm https://updater.linkly.ai/cli/install.ps1 | iex

crates.io からインストール（Rust ツールチェーンが必要）：

cargo install linkly-ai-cli

インストール完了後、インストールを確認します：

linkly --version

デフォルトでは、CLI は ~/.linkly/port ファイルを通じてローカルの Linkly AI Desktop アプリを自動的に検出して接続します。LAN やクラウドトンネル経由でリモートのデバイスに接続することもできます — 下記の接続モードを参照してください。

使い方

CLI は search → grep または outline → read の段階的なワークフローに従います：まず検索で対象ドキュメントを見つけ、次に grep でパターンを特定するか、アウトラインで構造を把握し、最後に具体的な内容を読み取ります。ユーザーが指すコンテナ（「Notion ノートの中で」「Dropbox の論文フォルダで」）の実際のパスがわからない場合は、search の前に find-paths を呼び出してパスを特定できます。

成功したコマンド出力の末尾には、[meta] now=2026-05-08T...Z という UTC タイムスタンプ行が付きます（JSON モードではトップレベルの _meta.now フィールド）。これは Desktop が AI アシスタントに「先月」などの相対日付を計算するために提供するメタ情報です。人間ユーザーは無視して構いません。スクリプト処理時は、最終行をフィルタしてから後続の解析を行うことを推奨します。

接続ステータスの確認

linkly status

Linkly AI Desktop の実行ステータス、バージョン番号、インデックス済みドキュメント数、インデックスステータスを返します。

ドキュメント検索

linkly search "キーワードまたはフレーズ"

ローカルドキュメントを検索し、最も関連性の高い結果リストを返します。タイトル、パス、マッチ度、内容スニペットが含まれます。 よく使うパラメータ：

# 返却件数を制限（デフォルト 20、最大 50）
linkly search "API 設計" --limit 5

# ドキュメントタイプでフィルター
linkly search "会議議事録" --type pdf,docx

# JSON 形式で出力（スクリプト処理に適しています）
linkly search "予算報告" --json

# 期間でフィルター（2024 年 Q3 の四半期報告書）
linkly search "quarterly report" --modified-after 2024-07-01 --modified-before 2024-09-30

# 時間順で並べ替え（「最新」「最古」など期間が定まらない場合）
linkly search "weekly retro" --time-sort newest --limit 5

# 音声・動画を、その中で話された内容から検索
linkly search "we decided to postpone" --type audio,video

# ファイルではなくノートを検索
linkly search "onboarding checklist" --scope notes

--modified-after / --modified-before は ISO 8601 UTC 形式を受け付けます：日付のみ 2024-01-01（00:00:00Z として扱われる）または完全な RFC 3339 タイムスタンプ 2024-01-01T00:00:00Z。--time-sort は newest / oldest を受け付け、省略すると BM25 + ベクトルのハイブリッド関連度順を保持します。

--scope notes は結果をノートに限定し、--library と --path-glob を無視します — これらのフィルターはエラーにならず、静かに破棄されます。

ドキュメントアウトラインの表示

linkly outline <DOC_ID>

ドキュメントの構造化されたアウトラインとメタデータを取得します。DOC_ID は検索結果から取得します。複数のドキュメントを一度に表示したり、- を指定して ID をパイプで渡したりできます：

linkly outline id1 id2 id3

# 検索でヒットしたすべてのドキュメントのアウトラインを、シェルのループなしで取得
linkly search "architecture" --json | jq -r '.results[].doc_id' | linkly outline -

アウトライン機能は Markdown、DOCX、PowerPoint (PPTX)、EPUB のドキュメントで最も効果的です。これらの形式の見出し構造を解析できます。プレーンテキストやブックマークのない PDF の場合は、read コマンドを直接使用することをお勧めします。

ドキュメント内のパターン検索

linkly grep <PATTERN> <DOC_ID>...

1 つまたは複数のドキュメント内で、正規表現パターンにマッチする箇所を検索します。特定のテキスト（用語、人名、日付、識別子など）を探す必要があるときに使用します：

# ドキュメント内でパターンを検索
linkly grep "useState" 456

# 大文字小文字を区別せず、前後の文脈行付きで検索
linkly grep "error|warning" 1044 -C 3 -i

# マッチ数のみをカウント
linkly grep "TODO" 591 --mode count

# マッチをページ分割（最初の 20 件をスキップし、次の 20 件を表示）
linkly grep "import" 302 --offset 20 --limit 20

# 検索でヒットしたすべてのドキュメントを横断して grep
linkly search "deployment" --json | jq -r '.results[].doc_id' \
  | linkly grep "docker|kubernetes" -

ドキュメント内容の読み取り

linkly read <DOC_ID>...

1 つまたは複数のドキュメントの完全な内容を読み取り、行番号付きのテキストを出力します。長いドキュメントの場合、ページ分割して読み取れます：

# 50 行目から 100 行を読み取る
linkly read <DOC_ID> --offset 50 --limit 100

# ページ内で参照されている画像の OCR テキストを含める
linkly read <DOC_ID> --image-text full

# 複数のドキュメントを一度に読み取る、または ID をパイプで渡す
linkly read id1 id2 id3
linkly search "onboarding" --json | jq -r '.results[].doc_id' | linkly read -

--json を指定した場合、複数のドキュメントは JSON Lines（1 行に 1 オブジェクト）として出力されます。ID が 1 つだけのときは従来どおり単一のオブジェクトを出力するため、既存のスクリプトに影響はありません。

ページ分割戦略： デフォルトでは 1 回に 200 行を読み取ります（最大 500 行）。長いドキュメントの場合、--offset を調整して段階的に読み取ります：

linkly read <DOC_ID> --offset 1 --limit 200    # 第 1-200 行
linkly read <DOC_ID> --offset 201 --limit 200  # 第 201-400 行
linkly read <DOC_ID> --offset 401 --limit 200  # 第 401-600 行

パス特定（find-paths）

linkly find-paths --patterns <キーワード,キーワード,...>

インデックス済みドキュメントのファイルパスフィールドに対してキーワードで曖昧マッチングを行い、フォルダ単位で集約して上位の候補ディレクトリを返します。search の補助ツールとして位置づけられており、ユーザーがコンテナを名前で示しているのに（「Notion ノートの中で」「Dropbox の論文フォルダで」）その実際のパスがわからないとき、まず find-paths で実際のパスを探し、返されたパスの特徴的なセグメントを search の --path-glob パラメータに渡します。フォルダ名に glob メタ文字（* ? [）が含まれる場合は、返された path_glob フィールドをそのまま使えます——すでにエスケープ済みで、そのフォルダに字面一致します。 典型的な 2 ステップワークフロー：

# Step 1：実際のパスを特定
linkly find-paths --patterns Notion,notion --limit 5
# 例：.../Documents/Notion-Export-abc/workspace（1240 ファイル）が返る

# Step 2：そのコンテナ内で内容検索
linkly search "shopping receipt" --path-glob "*Notion-Export*"

バリエーションマッチング： --patterns はカンマ区切りの複数キーワードを受け付け、内部で OR 関係でサブストリングマッチングを行います。1 回の呼び出しで複数のバリエーションを渡す（翻訳ペア、大文字小文字、既知のアプリ識別子など）ことを推奨します：

linkly find-paths --patterns Notion,notion,Notion-Export
linkly find-paths --patterns Slack,slack --library work-notes

find-paths は「フォルダを探す」ツールであり、「ファイルを探す」ツールではありません：キーワードがディレクトリセグメントにマッチした場合のみカウントされます。キーワードがファイル名セグメントにのみマッチする場合（「孤児ファイル」）、静かに破棄されます。マッチするファイルがあるはずなのに 0 件返る場合は、linkly search を --path-glob なしで直接呼び出すフォールバックを検討してください。

ノート

Linkly AI は短い Markdown のノートをライブラリフォルダ内に保存します。これらはアップロードされることのない通常のローカルファイルで、他のドキュメントと同じようにインデックスされます。

# 新しい順に一覧表示
linkly list --scope notes

# タグでフィルター
linkly list --scope notes --tags project,urgent

# ノートを 1 件書き込む
linkly note-save --mode create --content "Remember to renew the certificate" --tags ops

# 長い本文は引用符で囲まず、パイプで渡す
some-command | linkly note-save --mode create --content -

既存のノートを編集するには、その note_id と現在の version が必要です。どちらも linkly list --scope notes が返します：

linkly note-save --mode edit \
  --note-id <uuid> --base-version <version> \
  --tags ops --content "Updated text"

本文中の #タグ こそがノートのタグです——--tags でできるのは追加だけです（タグを削除するには内容から対応する #タグ を消します）。0.11.0 より古い Desktop では、編集時に --tags が必須で、全置換として扱われます。--base-version は同時実行チェックで、読み取り後にノートが変更されていた場合、上書きせずに NOTE_VERSION_CONFLICT で失敗します。ノートの内容は制限された Markdown のサブセット（段落、太字、取り消し線、リスト）です。見出し、コード、リンク、表は拒否されます。

シェル補完

linkly completions <SHELL>

bash、zsh、fish、powershell、elvish 用の補完スクリプトを出力します。

zsh
bash
fish
PowerShell

mkdir -p ~/.zfunc
linkly completions zsh > ~/.zfunc/_linkly
# まだ設定していない場合は ~/.zshrc に追加：
#   fpath=(~/.zfunc $fpath)
#   autoload -Uz compinit && compinit

linkly completions bash > /usr/local/etc/bash_completion.d/linkly

linkly completions fish > ~/.config/fish/completions/linkly.fish

linkly completions powershell | Out-String | Invoke-Expression

その後、新しいシェルを開いてください。このスクリプトは静的で、Linkly AI Desktop と通信することはありません。そのためアプリを終了していても動作し、プロンプトの表示が遅くなることもありません。

MCP モード

linkly mcp

stdio MCP サーバーモードで実行し、Linkly AI のツールを MCP 互換の AI クライアントに公開します。接続先（アップストリーム）によって、クライアントがアクセスできる範囲が決まります：

コマンド	アクセス範囲
`linkly mcp`	ローカルのデスクトップアプリ — ローカルのコンテンツのみ
`linkly mcp --endpoint <url>`	LAN 上のデスクトップアプリ — コンテンツの範囲は同じ
`linkly mcp --remote`	クラウドゲートウェイ — ローカルのコンテンツとリンク済みのクラウドライブラリ

クラウドライブラリにアクセスできるブリッジモードは --remote だけです。事前に API Key を保存しておく必要があります（リモートモードを参照）。

Claude Desktop などのローカル AI アプリの設定： 以下の内容を Claude Desktop などのアプリの設定ファイルに追加してください：

macOS / Linux
Windows

~/.config/Claude/claude_desktop_config.json を編集：

{
  "mcpServers": {
    "linkly-ai": {
      "command": "linkly",
      "args": ["mcp"]
    }
  }
}

%APPDATA%\Claude\claude_desktop_config.json を編集：

{
  "mcpServers": {
    "linkly-ai": {
      "command": "linkly",
      "args": ["mcp"]
    }
  }
}

Cursor の設定： Cursor で Settings → MCP Servers → Add Server を開き、以下を追加：

Name: linkly-ai
Command: linkly mcp

CLI のアップデート

linkly self-update

自動的に最新バージョンを確認してアップデートします。CLI は起動時にバックグラウンドで更新を確認し、新しいバージョンがある場合はこのコマンドの実行を促します。

接続モード

CLI は Linkly AI ナレッジベースに接続する方法を 3 つサポートしています：

モード	パラメータ	動作
ローカル	（デフォルト、追加パラメータ不要）	`~/.linkly/port` からデスクトップアプリを自動検出
LAN	`--endpoint <url> --token <token>`	ローカルネットワーク内の他のデバイスに直接接続
リモート	`--remote`	`https://mcp.linkly.ai` クラウドトンネル経由で接続、API Key が必要

ローカルモード（デフォルト）

追加のパラメータは不要です。CLI は ~/.linkly/port を読み取り、実行中のデスクトップアプリを検出します：

linkly search "machine learning"
linkly status

LAN モード

ローカルネットワーク内の他のデバイスで実行されている Linkly AI インスタンスに接続します。Token はデスクトップアプリの 設定 → MCP で確認できます：

linkly search "report" --endpoint http://192.168.1.100:60606/mcp --token your_lan_token
linkly status --endpoint http://192.168.1.100:60606/mcp --token your_lan_token

リモートモード

クラウドトンネル経由で、どこからでもナレッジベースに接続できます。まず API Key（linkly.ai/dashboard から取得）を保存します：

linkly auth set-key lkai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

続いて、任意のコマンドで --remote を使用します：

linkly search "machine learning" --remote
linkly status --remote

保存済みのキーは、いつでも確認・削除できます：

linkly auth status   # 使用中のキー、その有効性、プランを表示
linkly auth logout   # 保存された認証情報を削除

--endpoint と --token は LAN アクセス用で、必ず一緒に指定してください。--remote とは併用できません。リモートアクセスの場合は linkly auth set-key で API Key を保存してください。

パラメータ説明

グローバルオプション

オプション	適用範囲	説明
`--endpoint <URL>`	LAN	指定した MCP エンドポイントに接続（例：`http://192.168.1.100:60606/mcp`）、`--token` の指定が必要
`--token <token>`	LAN	LAN 認証用の Bearer Token（`--endpoint` と併用必須、`--remote` とは併用不可）
`--remote`	リモート	`https://mcp.linkly.ai` クラウドトンネル経由で接続（`--endpoint` とは併用不可）
`--json`	全コマンド	JSON 形式で出力（スクリプトや自動化に適しています）
`--exit-code`	全コマンド	「該当なし」（終了コード 1）と「失敗」（終了コード 2）を区別 — Exit Codes を参照
`-V, --version`	—	CLI バージョン番号を表示
`-h, --help`	—	ヘルプ情報を表示

--endpoint、--token、--remote はドキュメント系コマンド（search、grep、outline、read、list、note-save、find-paths、explore、list-libraries）に加え、status と doctor で使用できます。mcp コマンドは --endpoint または --remote を受け付けますが、--token は受け付けません。--json と --exit-code はすべてのコマンドで使用できます。

Exit Codes

デフォルトでは、CLI は慣例的な 2 つの値を使用します：成功時は 0、失敗時は 1。ここでの「成功」には「1 件も見つからなかった」場合も含まれる点に注意してください。ヒットのない検索でも終了コードは 0 です。 --exit-code を指定すると、この 2 つを区別できます：

終了コード	意味
`0`	実行に成功し、1 件以上の結果があった
`1`	実行自体は成功したが、該当する結果がなかった
`2`	失敗（接続、認証、不正な引数、エラーなど）

# 検索で実際に結果が見つかったときだけレポートを開く
linkly search "quarterly report" --exit-code && open-report

このフラグがオプトインなのは、1 の意味が変わるためです。指定しない場合、1 は「失敗」を意味し、既存のスクリプトはこれを前提に判定しています。

search パラメータ

パラメータ	説明	デフォルト値
`<QUERY>`	検索キーワードまたはフレーズ（必須）	—
`--limit <N>`	最大返却結果数（1-50）	20
`--type <TYPES>`	ドキュメントタイプでフィルター（カンマ区切り）：`pdf`、`docx`、`pptx`、`epub`、`md`、`txt`、`html`、`image`、`audio`、`video`	全部
`--library <NAME>`	特定のライブラリに検索を限定	—
`--path-glob <PATTERN>`	ファイルパスでフィルター（部分一致。任意の位置にマッチし、前後の `*` は不要）。実際のパスが不明な場合は、先に `linkly find-paths` を呼び出してください	—
`--modified-after <ISO>`	更新日時の下限（含む）。ISO 8601 UTC 形式：日付のみ `2024-01-01` または完全な `2024-01-01T00:00:00Z`	—
`--modified-before <ISO>`	更新日時の上限（含む）。形式は `--modified-after` と同じ	—
`--time-sort <MODE>`	時間順での並べ替え：`newest`（新しい順）/ `oldest`（古い順）。省略すると関連度順を保持	—
`--scope <SCOPE>`	`folder` はインデックス済みのすべてのコンテンツを検索。`notes` は結果をノートに限定し、`--library` / `--path-glob` を無視	folder
`--tags <LIST>`	カンマ区切りのノートタグ。すべてのタグを持つドキュメントのみを返す	—

find-paths パラメータ

パラメータ	説明	デフォルト値
`--patterns <LIST>`	カンマ区切りのキーワード一覧（必須）。複数のキーワードは OR 関係。1 回の呼び出しで複数のバリエーション（翻訳ペア、大文字小文字、既知のアプリ識別子など）を渡すことを推奨。ASCII は大文字小文字を区別しない、CJK は字面一致	—
`--library <NAME>`	特定のライブラリに限定	—
`--limit <N>`	候補ディレクトリの最大数（1-50）	10

outline パラメータ

パラメータ	説明	デフォルト値
`<ID>...`	ドキュメント ID（必須、複数指定可）。`-` を渡すと、標準入力から 1 行 1 件で ID を読み取る	—

grep パラメータ

パラメータ	説明	デフォルト値
`<PATTERN>`	正規表現パターン（必須）	—
`<DOC_ID>...`	検索対象のドキュメント ID（必須、複数指定可）。`-` を渡すと、標準入力から ID を読み取る	—
`-C, --context`	マッチ行の前後に表示する文脈行数	3
`-B, --before`	マッチ行の前に表示する文脈行数	—
`-A, --after`	マッチ行の後に表示する文脈行数	—
`-i`	大文字小文字を区別しないマッチング	—
`--mode`	出力モード：`content` または `count`	content
`--limit`	最大マッチ数（最大 100）	20
`--offset`	スキップするマッチ数（ページ分割用）	0
`--fuzzy-whitespace`	空白の曖昧マッチング：`true` で強制的に有効、`false` で強制的に無効、省略すると自動（PDF は有効、その他は無効）	自動

read パラメータ

パラメータ	説明	デフォルト値
`<ID>...`	ドキュメント ID（必須、複数指定可）。`-` を渡すと、標準入力から ID を読み取る	—
`--offset <N>`	開始行番号（1 から開始）	1
`--limit <N>`	読み取り行数（最大 500）	200
`--image-text <DETAIL>`	ページ内で参照されている画像の詳細度：`none`（対応関係のみ）、`abstract`（抜粋）、`full`（OCR テキストを埋め込み）	abstract

list パラメータ

パラメータ	説明	デフォルト値
`--scope <SCOPE>`	一覧表示するコンテナ：`folder`（ディレクトリ配下のインデックス済みファイル）、`library`（ライブラリのファイル）、`notes`（必須）	—
`--library <LIB>`	`--scope library` でどのライブラリか——ライブラリ名、`local://<id>`、または `cloud://<owner>/<slug>`（リモート）	—
`--path <DIR>`	列挙するディレクトリ——ローカルは絶対パス、クラウドライブラリは相対プレフィックス	—
`--type <LIST>`	カンマ区切りのドキュメント種別（`folder` / `library` のみ）。例：`pdf,docx`	すべて
`--modified-after <DATE>`	この日以降に更新された項目のみ（`folder` / `library` のみ）。ISO 8601、例：`2026-01-01`	—
`--modified-before <DATE>`	この日以前に更新された項目のみ。形式は同上	—
`--tags <LIST>`	カンマ区切りのタグ（`notes` のみ）。すべてのタグを持つ項目のみを返す	—
`--limit <N>`	最大件数（最大 200。スニペットが有効な間は 50 が上限）	50
`--offset <N>`	ページ分割のオフセット	0
`--sort <ORDER>`	`recent`（新しい順）、`oldest`（古い順）、`name`（名前順）	recent
`--snippet` / `--no-snippet`	項目ごとのスニペットを強制的に有効 / 無効にする（排他）。デフォルトは `notes` が有効、`folder` / `library` が無効	scope ごと

note-save パラメータ

パラメータ	説明	デフォルト値
`--mode <MODE>`	`create` は新しいノートを作成、`edit` は既存のノートを書き換える（`--note-id` と `--base-version` が必要）	—
`--content <TEXT>`	ノートの本文（必須）。`-` を渡すと標準入力から読み取る	—
`--note-id <UUID>`	編集対象のノート。`linkly list --scope notes` から取得	—
`--base-version <HASH>`	ノートの現在のバージョン。`linkly list --scope notes` から取得。その間にノートが変更されていた場合は書き込みを拒否	—
`--tags <LIST>`	カンマ区切りの、追加したいタグ——タグを削除するには内容から対応する `#タグ` を消す	—
`--app-name <NAME>`	この会話をホストしているアプリケーションの表示名。ノートの出典バッジとして表示される。最大 64 文字	—

completions パラメータ

パラメータ	説明	デフォルト値
`<SHELL>`	`bash`、`zsh`、`fish`、`powershell`、`elvish`（必須）	—

はじめに

主な機能

AI ツールと連携

AI Agent 向け

Linkly AI CLI の使い方

Linkly AI CLI の紹介

ターミナル検索

MCP ブリッジ

インストール

使い方

接続ステータスの確認

ドキュメント検索

ドキュメントアウトラインの表示

ドキュメント内のパターン検索

ドキュメント内容の読み取り

パス特定（find-paths）

ノート

シェル補完

MCP モード

CLI のアップデート

接続モード

ローカルモード（デフォルト）

LAN モード

リモートモード

パラメータ説明

グローバルオプション

Exit Codes

search パラメータ

find-paths パラメータ

outline パラメータ

grep パラメータ

read パラメータ

list パラメータ

note-save パラメータ

completions パラメータ

​Linkly AI CLI の紹介

ターミナル検索

MCP ブリッジ

​インストール

​使い方

​接続ステータスの確認

​ドキュメント検索

​ドキュメントアウトラインの表示

​ドキュメント内のパターン検索

​ドキュメント内容の読み取り

​パス特定（find-paths）

​ノート

​シェル補完

​MCP モード

​CLI のアップデート

​接続モード

​ローカルモード（デフォルト）

​LAN モード

​リモートモード

​パラメータ説明

​グローバルオプション

​Exit Codes

​search パラメータ

​find-paths パラメータ

​outline パラメータ

​grep パラメータ

​read パラメータ

​list パラメータ

​note-save パラメータ

​completions パラメータ

Linkly AI CLI の紹介

インストール

使い方

接続ステータスの確認

ドキュメント検索

ドキュメントアウトラインの表示

ドキュメント内のパターン検索

ドキュメント内容の読み取り

パス特定（find-paths）

ノート

シェル補完

MCP モード

CLI のアップデート

接続モード

ローカルモード（デフォルト）

LAN モード

リモートモード

パラメータ説明

グローバルオプション

Exit Codes

search パラメータ

find-paths パラメータ

outline パラメータ

grep パラメータ

read パラメータ

list パラメータ

note-save パラメータ

completions パラメータ