Mailru Cloud CLI

Неофициальный Python-CLI Mail.ru Облака клиент для майл ру, работающий через WebDAV

mailrucloud позволяет управлять файлами из терминала: загружать, скачивать, синхронизировать каталоги, получать информацию о файлах и многое другое. Проект вдохновлён gdrive и стремится предоставить такой же простой UX, но для Mail.ru Cloud.

---

📑 Содержание

• Mailru Cloud CLI
  • 📑 Содержание
  • 🚀 Возможности
  • 📦 Установка
    • Вариант 1: PyPI (стабильная версия)
    • Вариант 2: TestPyPI (текущие бета-релизы)
    • Вариант 3: Из исходников (рекомендуется для разработки)
  • ⚡️ Быстрый старт
  • 📚 Список команд
  • 🔍 Примеры использования
  • 🔄 Синхронизация каталогов
  • 🛣 Roadmap
  • 🛠 Сборка из исходников
  • 🤝 Contributing
  • 📝 Лицензия

---

🚀 Возможности

• Авторизация с использованием паролей приложений Mail.ru (2FA friendly)
• Просмотр содержимого облака (ls)
• Загрузка и скачивание файлов (upload, download)
• Одно/двухсторонняя синхронизация каталогов (sync push / pull / both)
• Удаление, перемещение, переименование файлов / папок (rm, mv)
• Получение подробной информации о файле (info)
• Чистый вывод в CLI и дружелюбные emoji-индикаторы
• 100 % тестовое покрытие fast-unit сценариев, CI на GitHub Actions
• Рекурсивная загрузка директорий с автоматическим созданием всех вложенных папок в облаке (sync push)

📦 Установка

Требования: Python ≥ 3.10

Вариант 1: PyPI (стабильная версия)

pip install mailru-cloud-cli

Если видите ошибку "externally-managed-environment", используйте виртуальное окружение:

python3 -m venv .venv --upgrade-deps
source .venv/bin/activate

Список команд

mailrucloud --help

Вариант 2: TestPyPI (текущие бета-релизы)

python -m pip install --upgrade \
  -i https://test.pypi.org/simple \
  --extra-index-url https://pypi.org/simple \
  mailru-cloud-cli==1.4.0

Вариант 3: Из исходников (рекомендуется для разработки)

git clone https://github.com/mueqee/mailrucloud.git
cd mailrucloud
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py --help

⚡️ Быстрый старт

# 1. Авторизация (email + пароль приложения Mail.ru)
mailrucloud login

# 2. Посмотреть содержимое корня
mailrucloud ls

# 3. Загрузить файл
mailrucloud upload ./photo.jpg /Photos/2024/

# 4. Скачать файл
mailrucloud download /Photos/2024/photo.jpg ./

При первой авторизации токен сохраняется в ~/.mailru_token.json.

📚 Список команд

Команда	Описание
login	Войти в облако Mail.ru
ls [REMOTE_DIR]	Список файлов/папок (default /)
upload <LOCAL_PATH> [--remote-path PATH]	Загрузка файла
download <REMOTE_PATH> [LOCAL_PATH]	Скачивание файла
sync [OPTIONS] <LOCAL_DIR> <REMOTE_DIR>	Синхронизация каталогов
rm <REMOTE_PATH>	Удаление файла/папки
mv <SRC> <DST>	Переименование/перемещение
info <REMOTE_PATH>	Подробная информация о файле

Все команды поддерживают флаг --help для подробной справки.

🔍 Примеры использования

# Рекурсивный вывод содержимого каталога
mailrucloud ls /Documents

# Односторонний бэкап (push)
mailrucloud sync ~/Projects /Backup --direction push

# Отобразить размер и дату изменения файла
mailrucloud info /Backup/report.pdf

# Удалить файл
mailrucloud rm /Backup/old.zip

🔄 Синхронизация каталогов

sync сопоставляет структуры директорий, копируя недостающие или изменённые файлы. Удаление в режиме both пока не отражается (безопасный режим). Алгоритм основан на сравнении хэшей и временных меток.

# Двусторонняя синхронизация (значение по умолчанию)
mailrucloud sync ~/Notes /CloudNotes

# Только из облака → локально
mailrucloud sync ~/Notes /CloudNotes -d pull

# Только локально → облако
mailrucloud sync ~/Notes /CloudNotes --direction push

# Быстрая многопоточная загрузка (8 потоков)
mailrucloud sync ~/Notes /CloudNotes --direction push --threads 8

# Загрузка только новых файлов (без проверки размера)
mailrucloud sync ~/Notes /CloudNotes --direction push --only-new

# Комбинированный режим для максимальной скорости
mailrucloud sync ~/Notes /CloudNotes --direction push --threads 8 --only-new

🛣 Roadmap

• Публикация стабильной версии в основное PyPI
• Рекурсивное создание директорий при загрузке (sync push)
• Многопоточная загрузка файлов для ускорения синхронизации
• Улучшенный прогресс-бар с процентами, счётчиком файлов и оставшимся временем
• Интерактивный TUI-режим (rich-console)
• Trusted Publishing для TestPyPI и PyPI (без API-токенов)
• Кроссплатформенная сборка и тестирование (Windows/macOS)
• Вывод прогресса операций через rich.progress
• Docker-образ mailrucloud для быстрого использования
• Генератор автокомплита Bash/Zsh/Fish для CLI

🛠 Сборка из исходников

Проект использует PEP 517 (setuptools). Локальная сборка:

python -m pip install --upgrade build
python -m build

Исходники пакуются в dist/.

🤝 Contributing

Pull requests приветствуются! Перед отправкой:

1. Создайте issue или обсудите идею в дискуссии.
2. Убедитесь, что pytest -v проходит локально.
3. Соблюдайте Conventional Commits на русском.
4. Запустите flake8 / mypy при необходимости.

📝 Лицензия

Пакет распространяется под лицензией MIT. Полный текст — в файле LICENSE.