# Облачные диски

`iola-cli` поддерживает личные облачные диски для бытовых сценариев: сохранить отчет, найти документ, сделать резервную копию, создать ссылку и собрать пакет документов.

Сейчас поддерживаются:

- Яндекс Диск;
- Облако Mail.ru через WebDAV.

Корпоративные хранилища, S3, Nextcloud и ownCloud в пользовательский контур не входят.

## Команды

```bash
iola cloud setup yandex-disk
iola cloud setup mailru-cloud
iola cloud status
iola cloud doctor
iola cloud use yandex-disk
iola cloud ls /IOLA
iola cloud mkdir /IOLA/Фото
iola cloud find "справка" --path /IOLA
iola cloud upload report.md /IOLA/reports/report.md
iola cloud download /IOLA/reports/report.md ./report.md
iola cloud share /IOLA/reports/report.md
iola cloud save --text "Текст заметки" --path /IOLA/notes/note.txt
iola cloud backup
```

## Яндекс Диск

Яндекс Диск подключается через OAuth-токен пользователя.

Новый рекомендуемый путь - через [Yandex Connector](Yandex-Connector). Он сохраняет общий OAuth-токен Яндекса и автоматически подключает его к провайдеру `yandex-disk`.

Старый прямой способ `iola cloud setup yandex-disk` остается доступным.

Официальная документация:

- REST API Диска: `https://yandex.ru/dev/disk/rest?lang=ru`
- получение OAuth-токена: `https://yandex.ru/dev/id/doc/ru/access`
- получение токена вручную для проверки: `https://yandex.ru/dev/id/doc/ru/tokens/debug-token`

### Получение OAuth-токена Яндекс Диска

1. Откройте страницу Яндекс OAuth: `https://oauth.yandex.ru/`.
2. Если Яндекс просит пройти верификацию через Госуслуги, пройдите ее. Без этого создание OAuth-приложения может быть недоступно.
3. Нажмите `Создать`.
4. В окне `Какое приложение хотите создать?` выберите `Для авторизации пользователей`.
5. Нажмите `Перейти к созданию`.
6. На шаге `Создание приложения` заполните:
   - `Название вашего сервиса`: например `iola-cli`;
   - `Иконка сервиса`: загрузите PNG-иконку до 1 МБ. Готовая иконка iola-cli доступна по ссылке: `https://raw.githubusercontent.com/adm-iola/iola-cli/main/docs/assets/iola-oauth-icon.png`;
   - `Почта для связи`: оставьте свою почту или укажите актуальную.
7. Нажмите `Продолжить`.
8. На шаге `Платформы приложений` выберите `Веб-сервисы`.
9. В поле `Redirect URI` укажите:

```text
https://oauth.yandex.ru/verification_code
```

10. Нажмите кнопку добавления рядом с `Redirect URI`, если интерфейс показывает такую кнопку.
11. В поле `Suggest Hostname`, если оно обязательно, укажите сайт проекта или любой понятный URL сервиса, например:

```text
https://github.com
```

12. Нажмите `Продолжить`.
13. На шаге `Права доступа к данным пользователей` не выбирайте лишние основные права: телефон, почта, дата рождения, профиль не нужны.
14. В блоке `Дополнительные` через поле `Название доступа` добавьте три права:
   - `Чтение всего Диска` / `cloud_api:disk.read`;
   - `Запись в любом месте на Диске` / `cloud_api:disk.write`;
   - `Доступ к информации о Диске` / `cloud_api:disk.info`.
15. Нажмите `Продолжить`.
16. На финальном экране проверьте, что приложение запрашивает только три права Диска.
17. Нажмите `Всё верно, создать приложение`.
18. На странице созданного приложения скопируйте `ClientID`.
19. Откройте ссылку, заменив `CLIENT_ID` на ваш `ClientID`:

```text
https://oauth.yandex.ru/authorize?response_type=token&client_id=CLIENT_ID
```

20. На экране авторизации нажмите `Войти как ...`.
21. Если Яндекс показывает предупреждение `Сервис ещё не верифицирован`, это нормально для личного приложения. Продолжайте только если приложение создавали вы сами и доверяете ему.
22. Яндекс перенаправит на страницу `verification_code`, где будет показан OAuth-токен. В адресной строке он также находится после `access_token=`.
23. Скопируйте OAuth-токен.
24. В CLI выполните:

```bash
iola cloud setup yandex-disk
```

25. Вставьте OAuth-токен.
26. Проверьте подключение:

```bash
iola cloud doctor
```

Секрет сохраняется локально в `~/.iola/secrets.json`.

После успешной проверки CLI создаст или использует папку `/IOLA` на Яндекс Диске.

Обычно такой токен выдается на длительный срок. Если доступ перестал работать, получите новый токен через ту же ссылку авторизации и повторите `iola cloud setup yandex-disk`.

После подключения можно работать с облаком обычными фразами в CLI:

```text
создай у меня на яндекс диске папку фото
покажи что лежит на яндекс диске
найди на яндекс диске справку
```

Такие запросы обрабатывает skill `personal-docs`. Они не требуют включать локальный режим `iola files mode`, потому что это не работа с файлами на ПК.

## Облако Mail.ru

Облако Mail.ru подключается через WebDAV.

Официальная инструкция Mail.ru по WebDAV: `https://help.mail.ru/cloud/desktop/webdav/`

Что сделать:

1. Войдите в аккаунт Mail.ru.
2. Создайте пароль для внешнего приложения. Для WebDAV обычный пароль от почты использовать не нужно.
3. В CLI выполните:

```bash
iola cloud setup mailru-cloud
```

4. Введите email и пароль внешнего приложения/WebDAV.
5. Проверьте подключение:

```bash
iola cloud doctor
```

Публичные ссылки через CLI сейчас поддерживаются только для Яндекс Диска. Для Mail.ru доступен список файлов, загрузка и скачивание через WebDAV.

## Безопасность

- OAuth-токены, пароли и API-ключи не попадают в резервные копии.
- `iola cloud backup` сохраняет конфигурацию без секретов.
- Удаление и массовое перемещение файлов в первом контуре не реализованы намеренно.
- Для локальных файлов продолжает действовать отдельный режим `iola files mode`.
