# Работа с CLI Яндекс Диска через ИИ-агента (/ru/docs/ydisk/usage)

Выберите папки Диска, текст которых хотите искать, обновляйте их копию и работайте с любым файлом на Диске вживую.
После этой страницы ваш агент отвечает по выбранным папкам и меняет файлы только там, где вы разрешили. Страница
считает, что вы уже [вошли](/llms.mdx/docs/ru/ydisk/installation/content.md).

**На этой странице:**

1. [Сначала профиль](#the-profile-comes-first)
2. [Выберите папки](#choose-folders)
3. [Синхронизация](#sync)
4. [Что хранит копия](#what-the-copy-holds)
5. [Читайте синхронизированный документ](#read-a-synced-document)
6. [Работа с файлами вживую](#work-with-files-live)
7. [Вывод для скриптов](#output-for-scripts)

## Сначала профиль [#сначала-профиль]

Профиль: имя, которое вы выбираете для одного аккаунта. Это первое слово каждой команды, которой нужен аккаунт:

```sh
ydisk personal status
```

`YDISK_PROFILE=personal` делает то же самое для одного сеанса оболочки. Профиль никогда не подставляется сам, даже
единственный. Команда без него останавливается с кодом выхода 2 и показывает профили на этом компьютере.

## Выберите папки [#выберите-папки]

`folders browse` показывает Диск по одному уровню, вживую, так что папку можно найти по ее пути:

```sh
ydisk personal folders browse
ydisk personal folders browse --folder /Documents
ydisk personal folders add /Documents/Contracts
```

Выбранная папка забирает все, что в ней лежит, вместе с вложенными папками. `folders list` показывает выбранные
папки, а `folders remove` убирает одну из них. Следующая синхронизация удалит ее документы из копии.

Выбирайте несколько папок с документами, а не весь Диск. Яндекс Диск не сообщает инструменту, что изменилось, поэтому
каждая синхронизация заново перечисляет все выбранные папки и их подпапки. Папка с фотографиями добавляет время на
перечисление и не добавляет текста для поиска.

## Синхронизация [#синхронизация]

```sh
ydisk personal sync
ydisk personal status
```

`sync` скачивает файлы, которые появились или изменили содержимое с прошлой синхронизации, и читает их текст. Файл,
удаленный с Диска, пропадает из копии. Файл, перенесенный внутри выбранных папок, сохраняет свои теги и заметки.

Одна синхронизация читает до 200 файлов (`--limit`) и перечисляет до 10 000 элементов, а потом запоминает, где
остановилась. Большая папка обрабатывается за несколько запусков: запускайте `sync` снова, пока `status` не покажет,
что работы не осталось. Остановка ничего не теряет, следующая синхронизация продолжит с того места, где закончила
предыдущая.

Запускайте `sync`, когда хотите обновить копию, например перед вопросом агенту о свежих файлах. В фоне ничего не
работает. `sync --rescan` читает все выбранные папки с начала. Выполните его один раз и дальше возвращайтесь к обычной
команде `sync`.

Выбранную папку, которую вы переименовали или перенесли на Диске, инструмент больше не находит, и ее документы
уходят из копии. Добавьте ее снова под новым путем.

## Что хранит копия [#что-хранит-копия]

| На Диске | В копии |
| --- | --- |
| PDF с текстовым слоем, Word `.docx`, Excel `.xlsx`, CSV, TSV, обычный текст, Markdown | Текст, имя, путь, размер и даты |
| Отсканированный PDF или картинка | Имя, путь и даты. Текста для чтения нет |
| Любой другой файл и любой файл больше 50 МБ | Имя, путь и даты |

`status` перечисляет каждый файл, сохраненный только по имени, с причиной. Сами файлы остаются на Диске, а копия
хранит их текст. Время хранится и показывается в UTC.

## Читайте синхронизированный документ [#читайте-синхронизированный-документ]

```sh
ydisk personal documents list
ydisk personal documents show 1a2b3c --json
ydisk personal documents export 1a2b3c --output ./contract.md
```

`documents show` выводит весь текст одного документа, который вы находите по id из `search` или `documents list`. Id
выше только пример. `documents export` записывает документ в новый файл Markdown. Теги, заметки и воспоминания
остаются при документе и никогда не попадают на Диск. Смотрите [поиск документа](/llms.mdx/docs/ru/ydisk/search/content.md).

## Работа с файлами вживую [#работа-с-файлами-вживую]

Команды `files` работают с Диском напрямую, синхронизация им не нужна. Пути это пути на Диске, например
`/Documents/plan.pdf`.

```sh
ydisk personal files list --folder /Documents
ydisk personal files show /Documents/plan.pdf
ydisk personal files download /Documents/plan.pdf --json
ydisk personal files download /Documents/plan.pdf --output ./plan.pdf
ydisk personal files upload ./notes.md --folder /Documents
ydisk personal files copy /Documents/plan.pdf --folder /Archive
ydisk personal files move /Documents/old.pdf --folder /Archive
ydisk personal files create /Projects/2026
ydisk personal files delete /Documents/old.pdf
ydisk personal files restore trash:/old.pdf
ydisk personal files publish /Documents/plan.pdf
ydisk personal files unpublish /Documents/plan.pdf
```

- `files download` без `--output` отвечает текстом файла, до 200 000 символов, так что агент читает файл вне
  выбранных папок, не сохраняя его.
- `files delete` переносит файл в корзину Диска, а `files restore` возвращает его по пути в корзине.
- `files publish` создает публичную ссылку, которую может открыть любой, у кого она есть. `files unpublish` закрывает
  ее.
- `--replace` при загрузке, копировании или переносе перезаписывает файл, который уже лежит по этому пути.

В терминале инструмент спрашивает перед удалением, перезаписью и публичной ссылкой. Через MCP спросить некого, поэтому
задайте эти разрешения для агента. Смотрите [настройки](/llms.mdx/docs/ru/ydisk/configuration/content.md#permissions). Добавьте `--dry-run` к любому
изменению, чтобы увидеть, что оно сделает, и ничего не менять.

Каждая операция API Диска Яндекса тоже есть как команда: `ydisk personal api list` перечисляет их, а
`ydisk personal api show resources-list` показывает параметры одной операции, не обращаясь к Яндексу.

## Вывод для скриптов [#вывод-для-скриптов]

Каждая команда, кроме `mcp serve`, принимает `--json` и печатает одно значение JSON в stdout. Ошибки идут в stderr
тоже как JSON, с полем `code`, по которому можно ветвиться, а у каждого вида сбоя свой код выхода. Их перечисляет
[справочник команд](/llms.mdx/docs/ru/ydisk/commands/content.md).

Дальше: [найдите документ](/llms.mdx/docs/ru/ydisk/search/content.md) или [подключите агента](/llms.mdx/docs/ru/ydisk/mcp/content.md).
