Справочник CLI
lv24-seo — командная строка движка. По умолчанию она только читает данные провайдеров, с флагом --json печатает один машиночитаемый конверт, а состояние провайдеров меняет только через три явно защищённые команды записи. Один и тот же исполняемый файл работает в Windows, macOS и Linux.
Таблица команд
Таблицу можно фильтровать по команде, группе или описанию. Имена команд и флаги одинаковы во всех локалях; переводится только документация вокруг них.
Начало работы 5
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo version --json | Вывести версию движка и имя пакета. | |
lv24-seo doctor --json | Офлайн-проверка Python, конфигурации, каталога данных и наличия токенов; без сетевых вызовов. | |
lv24-seo init --property https://example.com --data-dir ./data | Создать прокомментированный seo.toml и каталог данных; без --force не перезаписывает. | |
lv24-seo properties --json | Показать настроенных провайдеров, их цель и наличие токена. | |
lv24-seo stats --days 7 --lag-days 2 --json | KPI по провайдерам за текущее и предыдущее окно только для чтения; без записи в хранилище. |
Аутентификация 4
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo auth status --json | Показать, у каких провайдеров есть токен и откуда он берётся; значения не читаются. | |
lv24-seo auth set --provider gsc --stdin | Сохранить секрет провайдера из stdin в связке ключей ОС или в файле с правами 0600. | |
lv24-seo auth login --provider gsc | Показать шаги ручного получения токена для GSC или Яндекса; ничего не записывается. | |
lv24-seo auth logout --provider gsc | Удалить сохранённый секрет провайдера; значения из окружения остаются только для чтения. |
Конфигурация 1
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo config show --json | Показать действующую конфигурацию с маскировкой похожих на секреты ключей. |
Google Search Console 2
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo gsc query --start 2026-11-01 --end 2026-11-07 --dimensions query,page --limit 100 | Запросить аналитику поиска GSC за явный диапазон дат и по измерениям. | |
lv24-seo sitemap submit --property sc-domain:example.com --url https://example.com/sitemap.xml | Спланировать отправку sitemap в GSC; dry run без --allow-write возвращает confirm-токен. |
Яндекс Вебмастер 3
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo yandex queries --limit 100 --json | Топ запросов Яндекса для настроенного хоста. | |
lv24-seo yandex indexing --json | История индексации, события поиска, проблемы и счётчики для хоста. | |
lv24-seo yandex recrawl --url https://example.com/page | Спланировать очередь переобхода Яндекса; dry run без --allow-write возвращает confirm-токен. |
IndexNow 1
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo indexnow submit --host example.com --key your-indexnow-key --url https://example.com/page | Спланировать отправку в IndexNow; dry run без --allow-write возвращает confirm-токен. |
Обход и аудит 1
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo crawl --start https://example.com --max-urls 500 --json | Обойти сайт в пределах бюджета URL, прогнать все правила и сохранить страницы и проблемы. |
Отчёты 2
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo report weekly --days 7 --lag-days 2 --out reports/ | Собрать недельный дайджест, при желании записать report.json/report.html и доставить с --send. | |
lv24-seo report diff --markdown | Сравнить два сохранённых недельных снимка без вызовов провайдеров; --markdown печатает сводку для PR. |
Расписание 2
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo schedule install --kind weekly --print | Установить задание недельного или дневного отчёта или показать его с --print. | |
lv24-seo schedule print --cron "0 6 * * 1" --target systemd | Отрисовать артефакт cron, systemd или Task Scheduler Windows, не трогая хост. |
Агенты и MCP 4
| Команда | Описание | Копировать |
|---|---|---|
lv24-seo mcp serve --transport stdio | Запустить MCP-сервер через stdio или streamable HTTP. | |
lv24-seo install --client claude --print | Влить запись MCP-сервера в конфиг клиента; --print показывает JSON. | |
lv24-seo export tools --out schemas/tools.json | Записать реестр инструментов MCP в schemas/tools.json. | |
lv24-seo export skills --out skills | Скопировать упакованные навыки агентов в --out. |
Любая команда также принимает --help — он печатает актуальный список флагов установленной версии.
Общие соглашения
Конверт ответа
С флагом --json команда печатает ровно один JSON-документ и ничего больше:
{ "ok": true, "data": {}, "meta": { "version": "0.5.2", "duration_ms": 812 }, "warnings": [] }Неудачная команда использует ту же форму с ok: false и объектом error вместо data:
{ "ok": false, "error": { "code": "AUTH_REQUIRED", "message": "Google Search Console token is missing", "retryable": false, "next_action": "lv24-seo auth login --provider gsc" }, "meta": { "version": "0.5.2" }, "warnings": ["gsc: token missing"] }dataзависит от команды. Вmetaвсегда естьversion, часто добавляютсяduration_ms,truncated,data_age_days,limitations,localeилиcomplete.warnings— короткие строки для человека. Агрегирующие команды вродеstatsостаютсяok: true, если один провайдер упал: сбой учитывается вcoverageи попадает вwarnings.- Без
--jsonвыводится компактная текстовая сводка в stdout, затем предупреждения и строка ошибки. Ни один режим не печатает ANSI-цвета. config showдобавляетmeta.redacted: true; ключи, похожие на секреты, маскируются как***.
Коды выхода
| Код | Значение | Коды ошибок |
|---|---|---|
0 | Успех. Конверт ok: true. | — |
1 | Непредвиденный внутренний сбой. | INTERNAL |
2 | Ошибка использования или конфигурации. | INVALID_INPUT, CONFIG_INVALID, CONFIRM_REQUIRED, WRITE_DISABLED |
3 | Ошибка аутентификации. | AUTH_REQUIRED, AUTH_INVALID |
4 | Квота или сбой вышестоящего сервиса. | QUOTA_EXCEEDED, UPSTREAM_UNAVAILABLE |
5 | Частичный результат: усечённый вывод. | TRUNCATED |
WRITE_DISABLED даёт код 2, а не 4: запись отклонена до обращения к провайдеру. Код 5 зарезервирован для успешного конверта, который одновременно усечён и помечен meta.strict; в 0.5.2 ни один флаг не включает строгий режим, поэтому скриптам следует считать 5 частичным результатом, а не жёсткой ошибкой. Ориентируйтесь на код выхода и error.code, а не на текст для человека.
Конфигурация и флаги
--config PATHвыбирает конкретныйseo.toml. Путь должен существовать; отсутствующий файл — этоCONFIG_INVALID, а не тихий откат к умолчаниям. Разрешённый путь абсолютный и нормализованный, поэтому артефакты планировщика и относительные настройки не зависят от рабочего каталога процесса.- Без
--configдвижок ищет./seo.toml, затем пользовательский конфиг платформы (%APPDATA%\lv24-seo\config.tomlв Windows,~/.config/lv24-seo/config.tomlв Linux). - Переменные
LV24_SEO_*перекрывают значения из файла. Файлы.envне загружаются автоматически; экспортируйте переменные в оболочке или в unit-файле сервиса. mcp serve— долгоживущий сервер, он не принимает ни--json, ни--config.
doctor --json сообщает meta.data_dir и meta.data_dir_source (config, когда эффективный каталог абсолютный, working directory, когда относительный) и добавляет предупреждение, если относительный каталог неоднозначен рядом с конфигом. Относительный каталог не валит проверку.
Полный список ключей, умолчания и работа с секретами — в справочнике конфигурации.
Только чтение по умолчанию и шлюз записи
Менять состояние провайдера могут только sitemap submit, yandex recrawl и indexnow submit. Они работают в два шага:
- Запустите команду без
--confirm. Она вернёт пробный прогон сdata.plan,data.plan_hash,data.confirm_tokenиmeta.dry_run: true. - Задайте длинный случайный
LV24_SEO_WRITE_SECRETв той же оболочке и повторите запуск с--allow-write --confirm TOKENв течение пяти минут.
Токен — это HMAC от действия, цели, полного хеша плана и срока действия, поэтому изменение любого входа его аннулирует. При инициализированной рабочей области CLI подключает SQLite-журнал идемпотентности: повторный токен возвращает status: skipped с reason: duplicate, и провайдер вызывается один раз. Без каталога данных применение всё равно выполняется, но конверт предупреждает, что защита от повтора отключена на пять минут жизни токена; dry run не открывает журнал и не создаёт базу. IndexNow действительно отправляет URL. GSC sitemap submit и Yandex recrawl сейчас возвращают WRITE_DISABLED, а не делают вид, что вызов провайдера состоялся.
Логирование
Логирование опционально. LV24_SEO_LOG_LEVEL=INFO (или DEBUG, WARNING, …) устанавливает redacting-handler в CLI и lv24-seo mcp serve; если переменная не задана, конфигурация логирования вызывающего не меняется. Вывод — одна JSON-строка на запись, когда stderr не терминал, и обычная строка иначе. MCP-транспорт пишет только в stderr; stdout остаётся протоколом. Конверт --json остаётся стабильным интерфейсом диагностики.
Детерминизм и честность данных
- Даты — ISO-8601 (
2026-11-10); отметки времени — ISO-8601 UTC (2026-11-14T12:00:00+00:00). - Порядок полей в CLI стабилен, сохранённые снимки сериализуются с сортировкой ключей, а в видимом выводе нет случайных идентификаторов. Отчёты и диффы рассчитаны на сравнение между запусками.
- Ограниченные ответы несут
truncated,total,data_age_daysиlimitations[], где это применимо. Метрика, присутствующая только в одном окне, помечается как неизвестная, а не как ноль. --daysпринимает1..3660; большее значение падает сINVALID_INPUTи кодом2.- Ни одна команда не печатает токен, cookie или полный заголовок
Authorization.
Группы команд
| Группа | Команды | Что затрагивает |
|---|---|---|
| Start | version, doctor, init, properties, stats | Локальные файлы и окружение; stats читает KPI провайдеров без записи. |
| Authentication | auth status, auth set, auth login, auth logout | Локальное хранилище секретов; login только печатает инструкции. |
| Configuration | config show | Действующая конфигурация с замаскированными учётными данными. |
| Google Search Console | gsc query, sitemap submit | Запросы только на чтение; sitemap submit — защищённая запись. |
| Yandex Webmaster | yandex queries, yandex indexing, yandex recrawl | Запросы только на чтение; recrawl — защищённая запись. |
| IndexNow | indexnow submit | Защищённая запись, которая действительно отправляет URL. |
| Crawl and audit | crawl | Не зависит от провайдеров; сохраняет локальные страницы и проблемы, если настроено хранилище. |
| Reports | report weekly, report diff | weekly сохраняет локальный снимок; diff только читает. |
| Scheduling | schedule print, schedule install | print только рендерит; install пишет файлы планировщика хоста. |
| Agents and MCP | mcp serve, install, export tools, export skills | Конфиг хоста, сгенерированные файлы или локальный сервер. |
Примеры
Снимок для дашборда
lv24-seo stats --days 7 --lag-days 2 --jsonТолько чтение, хранилище не нужно. Сервисы всегда идут в порядке gsc, yandex_webmaster, yandex_metrika, bing, crux, psi; в metrics только реально полученные значения, без заполнения нулями и без сумм между движками. Сбой одного провайдера изолирован и увеличивает coverage.failed.
Search Console
lv24-seo gsc query --start 2026-11-01 --end 2026-11-07 --dimensions query,page --limit 100 --json--start и --end обязательны. Сокращения --days и переопределения --property нет: ресурс берётся из [providers.gsc] в seo.toml. Измерения перечисляются через запятую и ограничены query, page, country, device и date.
Яндекс
lv24-seo yandex queries --limit 100 --json
lv24-seo yandex indexing --jsonyandex queries возвращает верхние строки, а не полную связку запрос-страница: Яндекс отдаёт не более 3 000 запросов за период. yandex indexing показывает историю индексирования, число страниц в поиске, диагностику и события поисковых URL для настроенного host_id.
Обход
lv24-seo crawl --start https://example.com --max-urls 500 --jsonОбходчик соблюдает robots.txt, идёт по ссылкам того же хоста в ширину, запускает все правила и сохраняет страницы и проблемы, если настроено хранилище. data.sitemap_coverage сравнивает карту сайта с тем, что увидел обход, в шести корзинах. Если возвращается complete: false, затронутые корзины — кандидаты, а не подтверждённые находки; limitations[] называет усечённый вход.
Отчёты
lv24-seo report weekly --days 7 --lag-days 2 --out reports/ --json
lv24-seo report diff --markdownreport weekly собирает и сохраняет снимок; добавьте --send, чтобы доставить его через каналы, включённые в seo.toml. --out пишет канонический английский report.json и report.html на языке report.locale. report diff сравнивает два сохранённых недельных снимка, не обращается к провайдерам и требует двух запусков за разные периоды. --markdown печатает в stdout только Markdown; предупреждения идут в stderr.
Расписание
lv24-seo schedule print --cron "0 6 * * 1" --target systemd --json
lv24-seo schedule install --kind weekly --printprint рендерит артефакт, не трогая хост. install пишет блок cron, пользовательские unit-файлы systemd или XML Планировщика заданий, а сгенерированная задача запускает report weekly --send --json. В systemd и Windows конвертируются только простые выражения cron (M H * * * и M H * * DOW).
MCP и клиенты агентов
lv24-seo install --client cursor --print
lv24-seo mcp serve --transport http --port 8765install добавляет запись сервера lv24-seo в конфиг хоста, а не заменяет файл; --print показывает точный JSON. mcp serve по умолчанию использует stdio и принимает streamable HTTP с --transport http.
Аутентификация
lv24-seo auth status --json
lv24-seo auth set --provider gsc --stdinauth set читает секрет из stdin или скрытого запроса и кладёт его в связку ключей ОС либо в явно включённый файловый резерв с правами 0600. Печатается только {provider, stored, source}. auth status показывает наличие и источник (env, keyring, file, missing), но никогда — значение.
Экспорт
lv24-seo export tools --out schemas/tools.json
lv24-seo export skills --out skills/export tools пишет сгенерированный реестр MCP для агентов, не использующих MCP; export skills копирует упакованные файлы SKILL.md и их манифест. Обе команды пишут только локальные файлы.
См. также
Source: _source/engine-cli.md, _source/engine-mcp.md, _source/engine-releases-0.5.2.md; вывод --help версии 0.5.2 в репозитории движка.