> ## Documentation Index
> Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Linkly AI CLI の使い方

> Linkly AI CLI を使用して、より高い柔軟性とよりギークな体験を得る方法をご紹介します。

## Linkly AI CLI の紹介

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

<CardGroup cols={2}>
  <Card title="ターミナル検索" icon="terminal" iconType="duotone">
    コマンドラインから直接ドキュメントを検索。開発者やギークユーザーに最適です
  </Card>

  <Card title="MCP ブリッジ" icon="plug" iconType="duotone">
    stdio MCP モードで実行し、Claude Desktop、Cursor などの AI ツールから Linkly
    AI を呼び出せます
  </Card>
</CardGroup>

## インストール

<Tabs>
  <Tab title="macOS / Linux" icon="apple">
    ターミナルで以下を実行：

    ```bash theme={null}
    curl -sSL https://updater.linkly.ai/cli/install.sh | sh
    ```

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

    ```bash theme={null}
    brew tap LinklyAI/tap
    brew install linkly
    ```
  </Tab>

  <Tab title="Windows" icon="windows">
    PowerShell で以下を実行：

    ```powershell theme={null}
    irm https://updater.linkly.ai/cli/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Cargo" icon="box">
    [crates.io](https://crates.io/crates/linkly-ai-cli) からインストール（Rust ツールチェーンが必要）：

    ```bash theme={null}
    cargo install linkly-ai-cli
    ```
  </Tab>
</Tabs>

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

```bash theme={null}
linkly --version
```

<Note>
  CLI を実行する前に Linkly AI Desktop アプリを起動する必要があります。CLI は
  `~/.linkly/port` ファイルを通じてデスクトップアプリの MCP
  サービスを自動的に検出して接続します。
</Note>

## 使い方

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

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

### 接続ステータスの確認

```bash theme={null}
linkly status
```

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

### ドキュメント検索

```bash theme={null}
linkly search "キーワードまたはフレーズ"
```

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

**よく使うパラメータ：**

```bash theme={null}
# 返却件数を制限（デフォルト 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
```

<Tip>
  `--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 + ベクトルのハイブリッド関連度順を保持します。
</Tip>

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

```bash theme={null}
linkly outline <DOC_ID>
```

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

```bash theme={null}
linkly outline id1 id2 id3
```

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

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

```bash theme={null}
linkly read <DOC_ID>
```

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

```bash theme={null}
# 50 行目から 100 行を読み取る
linkly read <DOC_ID> --offset 50 --limit 100
```

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

```bash theme={null}
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）

```bash theme={null}
linkly find-paths --patterns <キーワード,キーワード,...>
```

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

**典型的な 2 ステップワークフロー：**

```bash theme={null}
# 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 回の呼び出しで複数のバリエーションを渡す**（翻訳ペア、大文字小文字、既知のアプリ識別子など）ことを推奨します：

```bash theme={null}
linkly find-paths --patterns Notion,notion,Notion-Export
linkly find-paths --patterns Slack,slack --library work-notes
```

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

### MCP モード

```bash theme={null}
linkly mcp
```

stdio MCP サーバーモードで実行し、Linkly AI のツールを MCP 互換の AI クライアントに公開します。

**Claude Desktop などのローカル AI アプリの設定：**

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

<Tabs>
  <Tab title="macOS / Linux">
    `~/.config/Claude/claude_desktop_config.json` を編集：

    ```json theme={null}
    {
      "mcpServers": {
        "linkly-ai": {
          "command": "linkly",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    `%APPDATA%\Claude\claude_desktop_config.json` を編集：

    ```json theme={null}
    {
      "mcpServers": {
        "linkly-ai": {
          "command": "linkly",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

**Cursor の設定：**

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

* Name: `linkly-ai`
* Command: `linkly mcp`

### CLI のアップデート

```bash theme={null}
linkly self-update
```

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

## パラメータ説明

### グローバルオプション

| オプション              | 説明                                             |
| ------------------ | ---------------------------------------------- |
| `--endpoint <URL>` | MCP エンドポイントを指定（デフォルトは `~/.linkly/port` から自動検出） |
| `--json`           | JSON 形式で出力（スクリプトや自動化に適しています）                   |
| `-V, --version`    | CLI バージョン番号を表示                                 |
| `-h, --help`       | ヘルプ情報を表示                                       |

### search パラメータ

| パラメータ                     | 説明                                                                                       | デフォルト値 |
| ------------------------- | ---------------------------------------------------------------------------------------- | ------ |
| `<QUERY>`                 | 検索キーワードまたはフレーズ（必須）                                                                       | --     |
| `--limit <N>`             | 最大返却結果数（1-50）                                                                            | 20     |
| `--type <TYPES>`          | ドキュメントタイプでフィルター（カンマ区切り、例：`pdf,md,docx,epub`）                                             | 全部     |
| `--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`（古い順）。省略すると関連度順を保持                                     | --     |

### find-paths パラメータ

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

### outline パラメータ

| パラメータ     | 説明                  | デフォルト値 |
| --------- | ------------------- | ------ |
| `<ID...>` | ドキュメント ID（必須、複数指定可） | --     |

### read パラメータ

| パラメータ          | 説明             | デフォルト値 |
| -------------- | -------------- | ------ |
| `<ID>`         | ドキュメント ID（必須）  | --     |
| `--offset <N>` | 開始行番号（1 から開始）  | 1      |
| `--limit <N>`  | 読み取り行数（最大 500） | 200    |