README

Консоль в стиле artisan для 1С-Битрикс поверх symfony/console — с агент-слоем для ИИ: любая команда умеет отдавать машиночитаемый JSON-конверт, самоописываться (manifest/describe), работать неинтерактивно и с детерминированными кодами возврата. Namespace — MB\Bitrix\Console\.

Пакет собирает команды из себя, из других mb4it-пакетов и из штатной консоли Битрикса (.settings.php['console']['commands']) в один бинарь bx.

Требования

PHP ^8.2
1С-Битрикс (ядро; модуль main)
symfony/console ^6.4|^7, psy/psysh ^0.12 (для tinker) — единственные обязательные зависимости

Опциональные пакеты-компаньоны (ставить не обязательно):

mb4it/bitrix-migration — добавляет команды migrate* / make:migration*;
mb4it/bitrix-support — тогда консоль работает на едином контейнере приложения (иначе — на собственном).

Быстрый старт

Пакет самодостаточен: обязательны только symfony/console + psy/psysh и ядро Битрикса — НЕ требует mb4it/bitrix-support.

composer require mb4it/bitrix-console

Пакеты-сателлиты подключаются автоматически через discovery: они объявляют провайдер в composer.json → extra.mb-console.providers, а Console\PackageManifest читает vendor/composer/installed.json. Так, mb4it/bitrix-migration добавляет команды migrate* — ручной регистрации не нужно.

Готовый бинарь появится как vendor/bin/bx. Всё работает сразу:

php vendor/bin/bx list                    # список команд
php vendor/bin/bx about                   # окружение и рантайм
php vendor/bin/bx manifest --format=json  # самоописание для ИИ-агента
php vendor/bin/bx tinker                  # REPL

Чтобы вызывать просто php bx …, поставьте точку входа в корень сайта одной командой (см. «bx в корне сайта»):

php vendor/bin/bx bx:install              # создаст ./bx в корне (DocumentRoot)
php bx list

vendor/bin/bx сам поднимает ядро Битрикса (CLI). Контейнер один на приложение с фолбэком: если установлен mb4it/bitrix-support, консоль подхватывает его общий контейнер приложения (те же сервисы, что и в вебе); если support нет — работает на собственном минимальном контейнере. Отдельного включения модулей не требуется.

Расположение vendor роли не играет — оно может быть в корне (vendor/bin/bx), в local/vendor/bin/bx или в vendor модуля: composer-прокси сам знает путь к своему autoload.php. Меняется только путь запуска (php local/vendor/bin/bx …).

DOCUMENT_ROOT ищется независимо от vendor: из переменной окружения BITRIX_DOCUMENT_ROOT, иначе поиском вверх от текущего каталога до папки с bitrix/. Поэтому запускайте из любого места внутри проекта, либо задайте env (например, для cron с cwd=/):

BITRIX_DOCUMENT_ROOT=/var/www/site php local/vendor/bin/bx migrate

Далее в примерах bx = php vendor/bin/bx. Для краткости добавьте в проект обёртку или shell-alias, например alias bx='php vendor/bin/bx'.

Команды видны и через штатную консоль Битрикса (php bitrix/modules/main/cli/bitrix.php <команда>) — мост через .settings.php.

Веб-контекст. Чтобы классы пакетов были доступны и вне CLI, подключите composer-автозагрузку как обычно в Bitrix-проекте (например, require vendor/autoload.php в local/php_interface/init.php).

`bx` в корне сайта

Чтобы разработчики вызывали просто php bx <команда>, установите точку входа в корень одной командой:

php vendor/bin/bx bx:install          # создаст ./bx в корне (DocumentRoot)
php bx list

bx:install генерирует самодостаточный CLI-only файл; путь к composer-автозагрузке вычисляется при установке (с фолбэками на local/vendor и vendor). Опции: --path (каталог), --name (имя файла, по умолчанию bx), --force (перезаписать). После переноса проекта перегенерируйте: bx bx:install --force.

Безопасность. Сгенерированный bx исполняется только из CLI: при обращении по HTTP отдаёт 404 и ничего не выполняет (консоль умеет tinker — выполнение произвольного PHP). Тем не менее для файла в веб-корне соблюдайте гигиену:

держите vendor/ вне веб-корня либо закройте к нему доступ на уровне сервера;
запретите прямой доступ к /bx (nginx: location = /bx { deny all; }; Apache: <Files "bx"> Require all denied </Files>).

Локальная разработка пакетов

Если пакеты подключаются как локальные path-репозитории (не с Packagist), добавьте их в repositories потребителя:

{
  "require": { "mb4it/bitrix-console": "@dev" },
  "repositories": [
    { "type": "path", "url": "/path/to/mb-bitrix-console" },
    { "type": "path", "url": "/path/to/mb-bitrix-migration" }
  ]
}

Агент-слой

Любая команда-наследник MB\Bitrix\Console\Command принимает глобальные опции:

--format=json — вместо человекочитаемого вывода отдаёт единый конверт;
--pretty — форматировать JSON.

Конверт (MB\Bitrix\Console\Output\Envelope):

{
  "ok": true,
  "command": "migrate",
  "exitCode": 0,
  "data": { "applied": ["2026_..._create_orders"], "count": 1 },
  "messages": [{ "level": "success", "text": "1 migration(s) applied." }],
  "error": null
}

При ошибке — ok:false, exitCode>0 и error:{type,class,message,code} (в т.ч. для ошибок уровня фреймворка: неизвестная команда, неверная опция).

Правила для агента:

в JSON-режиме команда неинтерактивна (никогда не блокируется на stdin);
деструктивные команды требуют --force, иначе отказ с exitCode=2;
коды возврата детерминированы (0 успех, 1 ошибка, 2 отказ).

Открытие возможностей без угадывания:

bx manifest --format=json          # все команды: аргументы, опции, флаг destructive, примеры
bx describe migrate --format=json  # одна команда детально

Справочник команд

Ядро / интроспекция

Команда	Назначение
`about`	Окружение и рантайм консоли.
`manifest`	Машиночитаемый список всех команд (discovery для ИИ).
`describe <command>`	Детальное описание одной команды.
`tinker`	REPL / выполнение PHP в поднятом приложении (см. ниже).
`bx:install`	Установить точку входа `bx` в корень сайта (см. «`bx` в корне сайта»).
`ai:skills`	Сгенерировать skill/инструкцию по консоли для ИИ-агента (`.claude/skills/bx-console/SKILL.md`).

Версионируемые миграции (движок — `mb4it/bitrix-migration`)

Команда	Опции	Деструктивно
`migrate`	`--module`, `--path`	нет
`migrate:status`	`--module`, `--path`	нет
`migrate:rollback`	`--step`, `--force`, `--module`, `--path`	да
`migrate:fresh`	`--force`, `--module`, `--path`	да
`make:migration <name>`	`--module`, `--path`	нет
`migrate:install`	—	нет

--module <id> — миграции в <module>/migrations/ с изоляцией в леджере. migrate:install создаёт таблицу-леджер mb_migration_version (идемпотентно).

Генераторы миграций из живых сущностей

Читают существующую сущность Битрикса и создают файл миграции (up() воссоздаёт, down() откатывает) через fluent-билдеры пакета mb4it/bitrix-migration. Стратегия переносимости: воссоздание по ID → фолбэк по XML_ID/коду. Все принимают --module/--path/--name (куда положить) и --format=json.

Команда	Что экспортирует
`make:migration:options <module>`	опции модуля (`b_option`)
`make:migration:iblock <id\|code>`	инфоблок + свойства + разделы
`make:migration:iblock-elements <id\|code>`	элементы + свойства (`--filter` JSON, `--ids`, `--limit`)
`make:migration:hlblock <id\|name>`	HL-блок + поля (UF)
`make:migration:hlblock-elements <id\|name>`	строки HL-блока (`--filter`, `--ids`, `--limit`)
`make:migration:agents`	агенты (`--for-module`)
`make:migration:mail`	почтовые типы событий + шаблоны (`--event`)
`make:migration:user-groups`	группы пользователей
`make:migration:users`	пользователи (`--filter`, `--ids`, `--limit`) — без хешей паролей
`make:migration:sitemap`	конфигурации sitemap (seo)

Те же билдеры доступны и для ручного написания миграций: \MB\Bitrix\Database\Migrations\Builders\OptionBuilder::make('main','x')->value('1')->apply();.

Жизненный цикл модуля (оркестратор `MB\Bitrix\Migration\Facade`)

Только при установленном mb4it/bitrix-support. Эти команды используют его оркестратор MB\Bitrix\Migration\Facade, поэтому в standalone-консоли (без support) они скрыты — bx list их не покажет.

Команда	Опции	Деструктивно
`module:install <id>`	`--only=files,storage,events,agents`	нет
`module:uninstall <id>`	`--only=...`, `--force`	да

Синхронизирует files → storage (ORM-таблицы) → events + агенты (через AgentManager). module:install идемпотентна.

Генераторы

Команда	Опции
`make:command <name>`	`--namespace`, `--path`, `--command`, `--description`, `--force`
`make:orm <name>`	`--namespace`, `--path`, `--table`, `--force` (создаёт `Storage\Base`)

Штатные генераторы Битрикса (make:agent, make:component, make:entity, make:controller, make:module, make:tablet …) доступны через bx как есть — дубли не создаются.

Служебные (read-only, удобны агенту)

Команда	Назначение
`cache:clear`	Очистить managed- и файловый кэш Битрикса.
`events:run`	Запустить крон-обработчик Битрикса (агенты + очередь почты/sender).
`module:list`	Установленные модули и версии.
`iblock:list`	Инфоблоки.
`hlblock:list`	Highload-блоки.
`agent:list`	Зарегистрированные агенты.

events:run заменяет крон-строку Битрикса — запускает bitrix/modules/main/tools/cron_events.php в отдельном PHP-процессе (свои константы BX_CRONTAB и т.д.) и возвращает его вывод/код:

* * * * * php /path/to/site/vendor/bin/bx events:run >/dev/null 2>&1

Инспекция: инфоблоки, настройки, события (read-only)

Инфоблоки принимают id или символьный код. Все команды поддерживают --format=json.

Команда	Назначение
`iblock:types`	Типы инфоблоков.
`iblock:info <id\|code>`	Метаданные ИБ + счётчики элементов/разделов.
`iblock:properties <id\|code>`	Свойства (код, тип, множ., связь, enum-значения).
`iblock:sections <id\|code>`	Разделы в порядке дерева.
`iblock:elements <id\|code>`	Элементы: `--filter` (JSON), `--select`, `--order` (JSON), `--limit`, `--offset`, `--with-props`.
`iblock:element <id\|code> <elId>`	Один элемент: все поля + свойства.
`option:list <module>`	Все опции модуля (`b_option`).
`option:get <module> <name>`	Одна опция (`--site`, `--default`).
`config:module [module]`	Секции `.settings.php` модуля (или проекта).
`event:handlers [module] [event]`	Постоянные обработчики (`b_module_to_module`).
`agent:run <id>` ⚠️	Ручной прогон одного агента (`--force`).

Пример запроса элементов:

bx iblock:elements news --filter='{"=ACTIVE":"Y","!PREVIEW_TEXT":false}' \
   --select='["ID","NAME","CODE"]' --order='{"SORT":"ASC"}' \
   --limit 20 --with-props --format=json

tinker

Аналог Laravel Tinker (на PsySH).

bx tinker                                    # интерактивный REPL ($app в скоупе)

# неинтерактивно (для агента) — вернуть значение через "return":
bx tinker -e "return \Bitrix\Main\ModuleManager::getVersion('main');" --format=json
echo "return 2 + 2;" | bx tinker --format=json

В JSON-режиме результат: data.result (строка), data.resultType, data.output (перехваченный вывод).

На Windows/PowerShell 5.1 пайп в stdin искажает кодировку — используйте --execute или cmd-пайп.

Как написать свою команду

Унаследуйте MB\Bitrix\Console\Command, реализуйте handle(): int:

<?php

declare(strict_types=1);

namespace Local\Console;

use MB\Bitrix\Console\Command;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Input\InputArgument;

#[AsCommand(name: 'orders:sync', description: 'Sync orders from ERP.')]
final class SyncOrdersCommand extends Command
{
    protected function configure(): void
    {
        $this->addArgument('since', InputArgument::OPTIONAL, 'ISO date.');
    }

    public function isDestructive(): bool { return false; }

    public function manifestMeta(): array
    {
        return ['examples' => ['bx orders:sync 2026-01-01 --format=json']];
    }

    protected function handle(): int
    {
        $since = (string) $this->input->getArgument('since');

        $this->data('since', $since);          // в машинный payload
        $this->note("Syncing since {$since}"); // строка (в text-режиме печатается)
        $this->textTable(['ID', 'Sum'], [[1, 100], [2, 200]]); // таблица только для человека
        $this->success('Done.');

        return self::SUCCESS;
    }
}

Заготовку можно получить командой: bx make:command SyncOrdersCommand.

Зарегистрируйте команду одним из двух способов:

а) через .settings.php модуля (виден и bx, и штатному bitrix.php):

return [
    'console' => [
        'value' => ['commands' => [\Local\Console\SyncOrdersCommand::class]],
        'readonly' => true,
    ],
];

б) через тег контейнера в своём ServiceProvider:

$this->app->tag([\Local\Console\SyncOrdersCommand::class], 'console.command');

При совпадении имени команды приоритет у зарегистрированных через пакет/тег над штатными командами Битрикса.

API базового `Command`

Член	Назначение
`handle(): int`	Тело команды. Верните `self::SUCCESS` / `FAILURE` / `INVALID`.
`$this->input`, `$this->output`, `$this->io`	Symfony input/output + `SymfonyStyle`.
`$this->app`	Общий контейнер (контракт `Console\Contracts\Container`): Foundation-приложение при наличии support, иначе собственный `Console\Container`.
`$this->format`	`text` или `json`.
`data($k, $v)` / `setData([...])`	Добавить в машинный payload (всегда).
`note()` / `warn()` / `success()`	Человеко-сообщения (в json уходят в `messages`).
`table($headers,$rows,$dataKey)`	Таблица: в text печатает, в json кладёт в `data[$dataKey]`.
`textTable($headers,$rows)`	Таблица только для человека (json берёт данные из `data()`).
`isDestructive(): bool`	`true` → требует `--force`.
`manifestMeta(): array`	Примеры/заметки для `manifest`/`describe`.

Что внутри

Класс	Назначение
`Kernel`	Резолвит контейнер (adopt Foundation ↔ свой), регистрирует провайдеры и команды (тег + `.settings.php`), запускает.
`Application`	`symfony/console` Application (autoexit off).
`Command`	Базовая команда с агент-слоем.
`Contracts\Container`	Контракт контейнера, общий для собственного и support-контейнера.
`Container`	Собственный минимальный контейнер (standalone-фолбэк).
`Container\SupportAdapter`	Обёртка над Foundation-контейнером support (единый контейнер).
`Container\ActiveContainer`	Статический холдер активного контейнера для команд.
`PackageManifest`	Discovery провайдеров из `extra.mb-console.providers`.
`CoreServiceProvider`	Регистрирует свои команды; `module:install/uninstall` — только при support.
`Output\Envelope`	Машиночитаемый конверт результата.
`Support\CommandDescriptor`	Интроспекция команды для `manifest`/`describe`.
`Support\StubGenerator`	Рендер стабов для `make:*`.
`Command\{About,Manifest,Describe,Tinker}Command`	Ядро/интроспекция/REPL.
`Command\Module\*`	`module:list` (всегда); `module:install`/`uninstall` — при support.
`Command\Make\*`	`make:command`, `make:orm`.
`Command\{Iblock,Hlblock,Option,Agent,System}\*`	Read-only инспекция и служебные команды.
`ServiceProvider`	Абстрактный базовый провайдер (сателлиты наследуют).

Команды migrate* / make:migration* живут в mb4it/bitrix-migration и приходят через его провайдер (discovery), а не из этого пакета.

Как это собирается (Kernel)

bootNativeModules() подключает модули с console.commands (в т.ч. поднимает Foundation-приложение support, если оно есть в проекте).
Резолв контейнера: SupportAdapter поверх Foundation при наличии support, иначе собственный Console\Container.
Команды из тега контейнера console.command (наши — в приоритете) + из .settings.php['console']['commands'] каждого модуля (совместимость с bitrix.php, дедуп по имени).
Итог — один symfony/console Application; bx и bitrix.php видят один набор.

Биндинги контейнера

Ключ	Класс
`StubGenerator::class`	`StubGenerator` (singleton)

Команды тегируются как console.command. Сателлиты (напр. mb4it/bitrix-migration) добавляют свои биндинги (migrator, репозиторий, PathRegistry …) через собственный провайдер.

mb4it/bitrix-console

包简介

README 文档

README

Требования

Быстрый старт

`bx` в корне сайта

Локальная разработка пакетов

Агент-слой

Справочник команд

Ядро / интроспекция

Версионируемые миграции (движок — `mb4it/bitrix-migration`)

Генераторы миграций из живых сущностей

Жизненный цикл модуля (оркестратор `MB\Bitrix\Migration\Facade`)

Генераторы

Служебные (read-only, удобны агенту)

Инспекция: инфоблоки, настройки, события (read-only)

tinker

Как написать свою команду

API базового `Command`

Что внутри

Как это собирается (Kernel)

Биндинги контейнера

统计信息

GitHub 信息

其他信息

承接程序开发

mb4it/bitrix-console

包简介

README 文档

README

Требования

Быстрый старт

bx в корне сайта

Локальная разработка пакетов

Агент-слой

Справочник команд

Ядро / интроспекция

Версионируемые миграции (движок — mb4it/bitrix-migration)

Генераторы миграций из живых сущностей

Жизненный цикл модуля (оркестратор MB\Bitrix\Migration\Facade)

Генераторы

Служебные (read-only, удобны агенту)

Инспекция: инфоблоки, настройки, события (read-only)

tinker

Как написать свою команду

API базового Command

Что внутри

Как это собирается (Kernel)

Биндинги контейнера

统计信息

GitHub 信息

其他信息

承接程序开发

`bx` в корне сайта

Версионируемые миграции (движок — `mb4it/bitrix-migration`)

Жизненный цикл модуля (оркестратор `MB\Bitrix\Migration\Facade`)

API базового `Command`