CLI «seomaster»: SEOMaster из командной строки (версия 127)

seomaster — командная оболочка над API: те же методы, те же права ключа, лимиты и коды ошибок. Нужна, когда проверки надо запускать из cron, скрипта или CI, быстро посмотреть сайты в терминале или передать данные другой программе. Отдельной логики в ней нет: набор команд, параметры и признаки операций читаются с сервиса (GET /api/v1/capabilities), поэтому список всегда совпадает с API и с инструментами MCP.

Установка

Нужны PHP 8.1+ и расширение curl (или allow_url_fopen). Файл самостоятельный, без установки пакетов:

cp bin/seomaster /usr/local/bin/seomaster && chmod +x /usr/local/bin/seomaster
# или без копирования: php bin/seomaster help

Настройка

Адрес сервиса и ключ API (кабинет → «API и вебхуки»). Для CLI заведите отдельный ключ с минимальным набором прав: так проще отозвать и видно в журнале.

Те же значения можно сохранить в файл (~/.config/seomaster/config.json, права 0600):

seomaster config set url https://seo.example
echo smk_… | seomaster config set key      # ключ читается со стандартного ввода
seomaster config show                      # ключ показан маской, указан источник каждого значения

Ключ нельзя передать параметром командной строки: он виден другим пользователям в списке процессов. Переменные окружения важнее файла. Параметр --server заменяет адрес на один запуск.

Команды

Имена команд те же, что в справочнике API (API_REFERENCE): seomaster site issues example.com, seomaster sites list, seomaster analyze start example.com. Полный список и справка:

seomaster help                      # все команды по группам
seomaster help site issues          # или: seomaster site issues --help
seomaster commands                  # таблица команд; --format json — для программ

Аргументы: домен, номер и другие обязательные поля пишутся по порядку без имени, остальное — параметрами --имя значение (или --имя=значение). Массивы — через запятую или повторением флага (--events rank,uptime). Логические — флагом: --fresh, --no-fresh. Адрес сайта с https:// сводится к домену. Тело запроса можно передать целиком: --data '{"profile":"shop"}', --data @файл.json или --data - (со стандартного ввода); отдельные параметры важнее.

seomaster sites list
seomaster site issues example.com --apply-profile
seomaster events --level bad --days 7 --limit 20
seomaster tasks set-status 42 done
seomaster webhooks add https://hook.example/x --events rank,issues

Утилиты и сводки

Все утилиты сервиса (раздел «Утилиты») доступны из консоли: seomaster utils list, seomaster utils show hash (поля и ограничения), seomaster utils run hash --text abc --algo md5. Поля утилиты передаются параметрами --имя значение; список полей — в utils show. Результат в терминале выводится готовыми блоками (таблицы, пары «ключ — значение», код, сравнение), в конвейере — JSON.

seomaster utils list --group text --q хеш
seomaster utils run counter --stdin < статья.txt          # текст со стандартного ввода
seomaster utils run counter --from-file text=статья.txt   # текст поля из файла
seomaster utils run meta --title "Заголовок" --description "Описание" --get result
seomaster utils run imgconv --file фото.png --format webp --save-dir ./out   # файлы результата — на диск
seomaster utils run utm --input '{"url":"https://example.com/","source":"news"}'
seomaster utils run hash --set text=a=b --dry-run          # показать запрос, не отправляя

Ключи: --stdin (текст со стандартного ввода в основное поле), --from-file [поле=]путь (текст из файла), --file [поле=]путь (файл целиком, base64; до 5 МБ), --input '{…}' (все поля одним JSON), --set поле=значение, --save-dir каталог (сохранить файлы результата). Утилиты, которые ходят на чужие сайты, требуют ключ с правом run и имеют отдельный часовой лимит; без него — код выхода 2. Выключенная администратором утилита — код 3.

Сводки: seomaster today — что важно сегодня (показатели, события, срочное), seomaster incidents --status open --days 30 — инциденты по сайтам.

Вывод

В терминале — таблица, в конвейере — JSON. Явно: --json, --table, --raw (ответ как есть), --format ndjson (по объекту на строку для списков). --get поле.вложенное печатает одно значение для скриптов:

seomaster auth whoami --get key.name
seomaster sites list --format ndjson | jq -r .host

Постраничные списки (--limit, --offset) сообщают в стандартный поток ошибок, с какого смещения продолжить. Данные идут только в стандартный вывод, сообщения — в стандартный поток ошибок.

Фоновые операции

analyze start и crawl start возвращают задание. --wait дожидается результата (по умолчанию до 300 секунд, --wait-timeout), иначе ход смотрите командой seomaster jobs show <номер>:

seomaster analyze start example.com --wait && seomaster site issues example.com

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

• Запись безопасно повторять: каждому изменяющему запросу CLI даёт Idempotency-Key (случайный или ваш, --idem-key); при сбое сети и при лимитах запрос повторяется с тем же ключом и не выполняется дважды.
• Удаление (sites remove, profile reset, webhooks remove) спрашивает подтверждение в терминале, а в скриптах требует --yes.
• --dry-run печатает запрос (ключ замаскирован) и ничего не отправляет.
• Ключ не печатается ни в выводе, ни в сообщениях об ошибках, перенаправления не выполняются.

Лимиты и повторы

Ответы limit (429), maintenance, idem_busy, server и разовые сбои сети повторяются: до --retries раз (по умолчанию 2), с паузой из Retry-After, но не дольше --max-wait секунд (60). Ответ not_ready (данных ещё нет) не повторяется.

Коды выхода

Для скриптов: case $? in 2) echo "проверьте ключ";; 3) sleep 60;; esac.

Кэш и автодополнение

Список команд сохраняется на час (~/.cache/seomaster/); --refresh обновляет его, а если сервис недоступен, используется сохранённый. Автодополнение: source <(seomaster completion bash) (для zsh — seomaster completion zsh).

Совместимость

CLI работает с API 1.x. Имена команд закреплены и не переименовываются, новые методы появляются в списке сами. Старые версии сервиса (до 127) не отдают параметры методов в /capabilities, CLI скажет об этом и предложит обновить сервис.