> ## 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 для поиска, чтения, заметок, MCP и удалённого доступа.

## Что такое Linkly AI CLI

`linkly` подключается к Desktop или облачному MCP и предоставляет инструменты в оболочке. Он особенно удобен ИИ-агентам, конвейерам и клиентам со stdio.

CLI не создаёт отдельный индекс: в локальном режиме Desktop должен быть запущен.

## Установка

<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 toolchain:

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

После установки откройте новый shell и проверьте:

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

<Note>По умолчанию CLI находит локальный Desktop через `~/.linkly/port`. Для другого устройства в LAN или облачного туннеля используйте [режимы подключения](#режимы-подключения) ниже.</Note>

## Основные команды

CLI следует процессу **search → grep или outline → read**. Если пользователь называет контейнер, но реальный путь неизвестен, сначала вызовите `find-paths`.

<Note>Успешный вывод заканчивается UTC-строкой `[meta] now=2026-05-08T...Z`, а JSON содержит `_meta.now`. Она нужна ИИ для расчёта относительных дат. Пользователь может её игнорировать; скрипт при необходимости должен удалить последнюю строку.</Note>

### Состояние

```bash theme={null}
linkly status
linkly status --json
linkly doctor
```

`status` возвращает состояние и версию Desktop, число проиндексированных документов и ход индексирования.

### Поиск

```bash theme={null}
linkly search "keywords or phrases"
linkly search "API design" --limit 5
linkly search "meeting minutes" --type pdf,docx
linkly search "budget report" --json
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
```

<Tip>`--modified-after` и `--modified-before` принимают UTC ISO 8601: дату либо полный RFC 3339. `--time-sort` принимает `newest` и `oldest`; без него сохраняется порядок BM25 + векторной релевантности.</Tip>

<Note>`--scope notes` ограничивает поиск заметками и игнорирует `--library` и `--path-glob`.</Note>

### Структура документа

```bash theme={null}
linkly outline <DOC_ID>
linkly outline id1 id2 id3
linkly search "architecture" --json | jq -r '.results[].doc_id' | linkly outline -
```

<Tip>Outline лучше всего работает с Markdown, DOCX, PPTX и EPUB. Для простого текста и PDF без закладок используйте `read`.</Tip>

### Поиск шаблона внутри документов

```bash theme={null}
linkly grep <PATTERN> <DOC_ID>...
linkly grep "useState" 456
linkly grep "error|warning" 1044 -C 3 -i
linkly grep "TODO" 591 --mode count
linkly grep "import" 302 --offset 20 --limit 20
linkly search "deployment" --json | jq -r '.results[].doc_id' \
  | linkly grep "docker|kubernetes" -
```

### Чтение

```bash theme={null}
linkly read <DOC_ID>...
linkly read <DOC_ID> --offset 50 --limit 100
linkly read <DOC_ID> --image-text full
linkly read id1 id2 id3
linkly search "onboarding" --json | jq -r '.results[].doc_id' | linkly read -
```

<Tip>При нескольких документах `--json` печатает JSON Lines — один объект на строку. Для одного ID остаётся один JSON-объект.</Tip>

Длинный документ читайте страницами:

```bash theme={null}
linkly read <DOC_ID> --offset 1 --limit 200
linkly read <DOC_ID> --offset 201 --limit 200
linkly read <DOC_ID> --offset 401 --limit 200
```

### Поиск путей

`find-paths` агрегирует каталоги, соответствующие вариантам имени, чтобы затем использовать `--path-glob`:

```bash theme={null}
linkly find-paths --patterns Notion,notion --limit 5
linkly search "shopping receipt" --path-glob "*Notion-Export*"
linkly find-paths --patterns Slack,slack --library work-notes
```

Передавайте несколько вариантов одним вызовом: они объединяются OR. Если шаблон совпал только с именем файла, а не сегментом каталога, результат отбрасывается; при нулевом ответе попробуйте `search` без `--path-glob`. Если имя каталога содержит `*`, `?` или `[`, копируйте уже экранированное поле `path_glob` из ответа.

### Notes

```bash theme={null}
linkly list --scope notes
linkly list --scope notes --tags project,urgent
linkly note-save --mode create --content "Не забыть обновить сертификат" --tags ops
some-command | linkly note-save --mode create --content -
```

Заметки — обычные локальные Markdown-файлы в папке библиотеки; они не загружаются в облако и индексируются как остальные документы. `note-save` — команда записи, поэтому ИИ вызывает её только по явному запросу пользователя.

Для редактирования сначала получите `note_id` и текущую `version` через `list`, прочитайте полное тело, затем передайте оба значения и полный новый текст:

```bash theme={null}
linkly note-save --mode edit \
  --note-id <uuid> --base-version <version> \
  --tags ops --content "Обновлённый текст"
```

<Warning>Встроенные `#tags` в теле являются тегами заметки. `--tags` только добавляет: для удаления уберите маркер из полного содержимого. Desktop старше 0.11.0 требует `--tags` при редактировании и заменяет весь набор. `--base-version` защищает от конкурентного изменения: команда вернёт `NOTE_VERSION_CONFLICT`, а не перезапишет чужую правку. Разрешены абзацы, жирный и зачёркнутый текст и списки; заголовки, код, ссылки и таблицы отклоняются.</Warning>

### Автодополнение

```bash theme={null}
linkly completions <SHELL>
```

Печатает статический скрипт для `bash`, `zsh`, `fish`, `powershell` или `elvish`.

<Tabs>
  <Tab title="zsh">
    ```bash theme={null}
    mkdir -p ~/.zfunc
    linkly completions zsh > ~/.zfunc/_linkly
    # Добавьте в ~/.zshrc:
    #   fpath=(~/.zfunc $fpath)
    #   autoload -Uz compinit && compinit
    ```
  </Tab>

  <Tab title="bash">
    ```bash theme={null}
    linkly completions bash > /usr/local/etc/bash_completion.d/linkly
    ```
  </Tab>

  <Tab title="fish">
    ```bash theme={null}
    linkly completions fish > ~/.config/fish/completions/linkly.fish
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={null}
    linkly completions powershell | Out-String | Invoke-Expression
    ```
  </Tab>
</Tabs>

После этого откройте новый shell. Скрипт не обращается к Desktop и не замедляет приглашение.

### Режим MCP

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

Команда запускает stdio MCP-сервер для совместимых ИИ-клиентов. Направление определяет доступный контент:

| Команда                       | Куда подключается                                                   |
| ----------------------------- | ------------------------------------------------------------------- |
| `linkly mcp`                  | Локальный Desktop и только локальный контент                        |
| `linkly mcp --endpoint <url>` | Desktop в LAN с теми же границами данных                            |
| `linkly mcp --remote`         | Облачный шлюз, локальный контент и подключённые облачные библиотеки |

<Tip>Только `--remote` даёт мосту доступ к облачным библиотекам и требует заранее сохранённый API key.</Tip>

Для Claude Desktop добавьте в `~/.config/Claude/claude_desktop_config.json` на macOS/Linux или `%APPDATA%\Claude\claude_desktop_config.json` на Windows:

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

В Cursor откройте **Settings → MCP Servers → Add Server** и задайте имя `linkly-ai`, команду `linkly mcp`.

### Обновление

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

Команда проверяет и устанавливает последнюю версию. CLI также проверяет обновления в фоне при запуске и подсказывает выполнить её.

## Режимы подключения

| Режим     | Флаги                              | Как работает                                                  |
| --------- | ---------------------------------- | ------------------------------------------------------------- |
| Локальный | Без флагов                         | Автоматически читает порт Desktop из `~/.linkly/port`         |
| LAN       | `--endpoint <url> --token <token>` | Напрямую подключается к другому устройству в локальной сети   |
| Удалённый | `--remote`                         | Использует облачный туннель `https://mcp.linkly.ai` и API key |

### Локальный

```bash theme={null}
linkly search "machine learning"
linkly status
```

Используется локальный Desktop и фактический порт из настроек.

### LAN

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

### Удалённый

```bash theme={null}
linkly auth set-key lkai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
linkly search "machine learning" --remote
linkly status --remote
linkly auth status
linkly auth logout
```

Для облачной библиотеки добавьте `--library cloud://username/slug`.

<Warning>`--endpoint` и `--token` для LAN обязательны вместе и несовместимы с `--remote`. Для удалённого режима заранее сохраните ключ через `linkly auth set-key`.</Warning>

## Справочник параметров

### Глобальные параметры

| Параметр           | Область     | Назначение                                                           |
| ------------------ | ----------- | -------------------------------------------------------------------- |
| `--endpoint <URL>` | LAN         | Конкретный MCP endpoint; требует `--token`                           |
| `--token <TOKEN>`  | LAN         | Bearer-токен, обязателен с `--endpoint` и несовместим с `--remote`   |
| `--remote`         | Remote      | Облачный туннель `https://mcp.linkly.ai`, несовместим с `--endpoint` |
| `--json`           | Все команды | Машиночитаемый JSON                                                  |
| `--exit-code`      | Все команды | Отличать «ничего не найдено» (1) от ошибки (2)                       |
| `-V, --version`    | —           | Версия CLI                                                           |
| `-h, --help`       | —           | Справка                                                              |

<Tip>`--endpoint`, `--token`, `--remote` работают у документных команд, `status` и `doctor`. `mcp` принимает `--endpoint` или `--remote`, но не `--token`. `--json` и `--exit-code` доступны везде.</Tip>

### Коды завершения

Без флага используются обычные значения: `0` — успех, `1` — ошибка; пустой результат считается успехом. С `--exit-code`:

| Код | Значение                                                   |
| --- | ---------------------------------------------------------- |
| `0` | Команда выполнена и вернула хотя бы один результат         |
| `1` | Команда выполнена, но ничего не найдено                    |
| `2` | Ошибка подключения, авторизации, аргументов или выполнения |

```bash theme={null}
linkly search "quarterly report" --exit-code && open-report
```

<Note>Флаг необязателен, потому что меняет смысл кода `1`; существующие сценарии без него продолжают трактовать `1` как ошибку.</Note>

### Параметры search

| Параметр                  | Описание                                                                                            | По умолчанию |
| ------------------------- | --------------------------------------------------------------------------------------------------- | ------------ |
| `<QUERY>`                 | Обязательные ключевые слова или фраза                                                               | —            |
| `--limit <N>`             | Число результатов, 1–50                                                                             | 20           |
| `--type <TYPES>`          | Список через запятую: `pdf`, `docx`, `pptx`, `epub`, `md`, `txt`, `html`, `image`, `audio`, `video` | Все          |
| `--library <NAME>`        | Ограничение одной библиотекой                                                                       | —            |
| `--path-glob <PATTERN>`   | Подстрочный фильтр пути; если путь неизвестен, сначала `find-paths`                                 | —            |
| `--modified-after <ISO>`  | Включительная нижняя временная граница                                                              | —            |
| `--modified-before <ISO>` | Включительная верхняя временная граница                                                             | —            |
| `--time-sort <MODE>`      | `newest` или `oldest`; без него порядок по релевантности                                            | —            |
| `--scope <SCOPE>`         | `folder` либо `notes`; заметки игнорируют library/path                                              | folder       |
| `--tags <LIST>`           | AND-фильтр тегов заметок                                                                            | —            |

### Параметры find-paths

| Параметр            | Описание                                             | По умолчанию |
| ------------------- | ---------------------------------------------------- | ------------ |
| `--patterns <LIST>` | Обязательные варианты через запятую, объединённые OR | —            |
| `--library <NAME>`  | Конкретная библиотека                                | —            |
| `--limit <N>`       | Число каталогов, 1–50                                | 10           |

### Параметры outline

| Параметр  | Описание                                                                       |
| --------- | ------------------------------------------------------------------------------ |
| `<ID>...` | Один или несколько обязательных ID; `-` читает по одному ID на строку из stdin |

### Параметры grep

| Параметр                       | Описание                                                     | По умолчанию |
| ------------------------------ | ------------------------------------------------------------ | ------------ |
| `<PATTERN>`                    | Обязательное регулярное выражение                            | —            |
| `<DOC_ID>...`                  | Один или несколько ID; `-` читает stdin                      | —            |
| `-C, --context`                | Строки до и после                                            | 3            |
| `-B, --before` / `-A, --after` | Отдельный контекст до/после                                  | —            |
| `-i`                           | Без учёта регистра                                           | —            |
| `--mode`                       | `content` или `count`                                        | content      |
| `--limit` / `--offset`         | Максимум совпадений (до 100) / пропуск для пагинации         | 20 / 0       |
| `--fuzzy-whitespace`           | `true`, `false` или авто (PDF включено, остальные выключены) | auto         |

### Параметры read

| Параметр                | Описание                                | По умолчанию |
| ----------------------- | --------------------------------------- | ------------ |
| `<ID>...`               | Один или несколько ID; `-` читает stdin | —            |
| `--offset <N>`          | Первая строка                           | 1            |
| `--limit <N>`           | Число строк, максимум 500               | 200          |
| `--image-text <DETAIL>` | `none`, `abstract` или `full`           | abstract     |

### Параметры list

| Параметр                                 | Описание                                                        | По умолчанию |
| ---------------------------------------- | --------------------------------------------------------------- | ------------ |
| `--scope <SCOPE>`                        | Обязательный контейнер `folder`, `library` или `notes`          | —            |
| `--library <LIB>`                        | Имя, `local://<id>` или облачный `cloud://<owner>/<slug>`       | —            |
| `--path <DIR>`                           | Абсолютный локальный каталог или относительный облачный префикс | —            |
| `--type <LIST>`                          | Типы через запятую только для folder/library                    | Все          |
| `--modified-after` / `--modified-before` | Временные границы только для folder/library                     | —            |
| `--tags <LIST>`                          | AND-теги только для notes                                       | —            |
| `--limit <N>` / `--offset <N>`           | Размер страницы (до 200, со сниппетами 50) / смещение           | 50 / 0       |
| `--sort <ORDER>`                         | `recent`, `oldest` или `name`                                   | recent       |
| `--snippet` / `--no-snippet`             | Принудительно включить/выключить сниппеты                       | По области   |

### Параметры note-save

| Параметр                | Описание                                                     |
| ----------------------- | ------------------------------------------------------------ |
| `--mode <MODE>`         | `create` либо `edit`; для edit нужны ID и version            |
| `--content <TEXT>`      | Обязательное полное тело; `-` читает stdin                   |
| `--note-id <UUID>`      | ID редактируемой заметки из `list`                           |
| `--base-version <HASH>` | Текущая версия; предотвращает перезапись конкурентных правок |
| `--tags <LIST>`         | Теги только для добавления; удаляйте `#tag` из тела          |
| `--app-name <NAME>`     | Имя приложения-источника, максимум 64 символа                |

### Параметры completions

`<SHELL>` обязателен: `bash`, `zsh`, `fish`, `powershell` или `elvish`.

Актуальные параметры также доступны через `linkly <command> --help` и в [справочнике инструментов](/docs/ru/tools-intro).