Всем привет! CLI-инструменты являются неотъемлемой частью любого PHP-фреймворка, они удобны для выполнения службных операций. В данной статье поговорим о том, какой инструментарий предоставляет нам Битрикс для разработки и обслуживания сайтов.

Доступные CLI-инструменты

Туллинг для работы в консольном режиме с проектом на Битрикс делится на 2 части:

1. Для фронтенда и Javascript: bitrix/cli для работы с расширениями.

2. Для бэкенда и PHP: bitrix.php для работы с бэкенд-сущностями, сервером, системой обновлений и т.д.

В данной статье речь пойдёт про второй пункт, а именно бэкенд-команды. Точкой входа в консольные команды является файл bitrix.php, который находится в директории bitrix корневой директории сайта.

Прежде чем его использовать, нужно выполнить установку необходимых библиотек и конфигурацию composer. Подробнее узнать о том, как настраивать composer в рамках Битрикс, вы можете в документации.

Запуск и механика работы

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

cd /path/to/document-root/bitrix

# если вы работаете изнутри BitrixVM, для сайта по умолчанию
cd /home/bitrix/www/bitrix

# если вы работаете изнутри BitrixVM, для конкретного сайта
cd /home/bitrix/ext_www/example.ru/bitrix

И посмотрим все доступные нам команды php bitrix.php list:

Available commands:
  completion             Dump the shell completion script
  help                   Display help for a command
  list                   List commands
 make
  make:agent             Make agent class
  make:component         Create a simple component with a class and a template
  make:controller        Make controller class
  make:entity            Make entity class for any business logic
  make:event             Make event class
  make:eventhandler      Make event handler class
  make:message           Make message object class
  make:messagehandler    Make message handler object class
  make:module            Make module folder with general files
  make:request           Make request object of controller
  make:service           Make service layer class
  make:tablet            Make ORM tablet for table
 messenger
  messenger:consume      Run Messenger's worker
 orm
  orm:annotate           Scans project for ORM Entities.
 translate
  translate:index        Indexes project for localization language files.
 update
  update:languages       Updates language files.
  update:modules         Updates modules.
  update:versions        Updates modules versions

ВАЖНО: в зависимости от версии модулей, которые используются у вас на проекте этот список может отличаться!

Для того чтобы узнать детальную информацию о конкретной команде, нужно вызвать команду help с именем команды, либо использовать опцию --help при вызове необходимой команды:

php bitrix.php help make:controller

# или
php bitrix.php make:controller --help

В ответ будет выведена детальная информация по команде и варианты её запуска:

Description:
  Make controller class

Usage:
  make:controller [options] [--] <name>

Arguments:
  name                   controller name

Options:
  -m, --module=MODULE    Module id
      --psr4|--no-psr4
      --alias=ALIAS      Controller's namespace alias from .settings.php
      --actions=ACTIONS  Comma-separated names of actions. Use alias "crud" for CRUD actions
  -P, --prefix=PREFIX    Prefix for the standard namespace for the generated class.
  -C, --context=CONTEXT  Namespace of context for the generated class.
  -h, --help             Display help for the given command. When no command is given display help for the list command
      --silent           Do not output any message
  -q, --quiet            Only errors are displayed. All other output is suppressed
  -V, --version          Display this application version
      --ansi|--no-ansi   Force (or disable --no-ansi) ANSI output
  -n, --no-interaction   Do not ask any interactive question
  -v|vv|vvv, --verbose   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  Make controller class.

  Example of simple creation. In interactive mode, the system will ask you for the necessary parameters:
  php bitrix.php make:controller post

  Example of creation with module option:
  php bitrix.php make:controller post -m my.module

  Example of creation with module option:
  php bitrix.php make:controller post -m my.module

  You can specify a comma-separated list of required actions that will be generated:
  php bitrix.php make:controller post -m my.module --actions=list,get,add,update,delete

  You can also use the shortcode `crud` to generate standard actions:
  php bitrix.php make:controller post -m my.module --actions=crud

  If you want to disable the interactive mode, then the `-n` option is used, then no questions will be asked:
  php bitrix.php make:controller post -m my.module -n

  By default, the class will be placed in the standard namespace.
  If you want to place it in a specific sub-namespace of the module, use the `-P` option.:
  php bitrix.php make:controller post -P V2

  If for some reason you do not want to generate the namespace and path in the PSR-4 format, you can send the `--no-psr` option.

Make команды

Команды из данной категории нужны для генерации различных сущностей системы, что позволяет избегать ручной работы по созданию и наполнению классов, а также снимает головную боль по расположению и неймингу.

В большинстве случаев, если вы не указываете опции, команда запросит их у вас в ходе выполнения, в интерактивном режиме. Некоторые опции можно не указывать, просто нажимая Enter.

Чтобы команда отработала сразу, без интерактивного режима, нужно указать опцию --no-interaction или -n и все обязательные опции. Почти всегда обязательно указывать модуль (опции --module или -m), в котором генерируется файл/сущность:

php bitrix.php make:agent MyAgent -n -m my.module

Если в модуле несколько бизнес-контекстов, то при генерации можно сразу указать нужный с помощью опции --context или её псевдонима -C. В примере ниже, будет создан файл /local/modules/my.module/lib/Infrastructure/Agent/FeatureName/MyAgentAgent.php:

php bitrix.php make:agent MyAgent -n -m my.module -C FeatureName

Если в модуле есть необходимость группировать API на верхнем уровне, можно указать префикс с помощью опции --prefix или её псевдонима -P. В примере ниже, будет создан файл /local/modules/my.module/lib/V2/Infrastructure/Controller/MyPost.php:

php bitrix.php make:controller MyPost -n -m my.module -P V2

Поддерживает ли команда указанные опции, можно узнать с помощью вызова подсказки --help.

make:module

Модуль - это минимальная логическая единица в системе. Подробнее можно узнать из документации.

При вызове команды указываем имя модуля:

~$ php bitrix.php make:module my.module

Module version [default: 1.0.0]:
Module name: My testing module
Module description: For tests

The files have been created:
 - /app/public/portal/local/modules/my.module/install/version.php
 - /app/public/portal/local/modules/my.module/install/index.php
 - /app/public/portal/local/modules/my.module/install/mysql/install.sql
 - /app/public/portal/local/modules/my.module/install/mysql/uninstall.sql
 - /app/public/portal/local/modules/my.module/default_option.php
 - /app/public/portal/local/modules/my.module/lang/ru/install/index.php

После выполнения будет создана минимальная структура для работы с модулями. Название и описание используются для отображение в админке, в списке модулей.

make:controller

Контроллер — это контроллер :) Подробнее можно узнать из документации.

При вызове команды указываем имя контроллера:

~$ php bitrix.php make:controller MyPost

Module id: my.module
Comma-separated names of actions. Use alias "crud" for CRUD actions:
Controller's namespace alias from .settings.php:
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Infrastructure/Controller/MyPost.php

Для генерации сразу же нужных действий контроллера можно использовать опцию --actions, в которой через запятую указать нужные экшены:

php bitrix.php make:controller MyPost -n -m my.module --actions get,list

Для типовых CRUD операций, есть псевдоним crud, который подразумевает действия list,get,add,update,delete:

php bitrix.php make:controller MyPost -n -m my.module --actions crud

Если контроллер располагается не в пространстве имен по умолчанию, то можно указать ему --alias, чтобы в докблоке к экшенам был сформирован правильный путь вызова:

php bitrix.php make:controller MyPost -n -m my.module --actions crud --alias cloud

Подробнее про пространства в контроллерах читайте в документации.

make:request

В контексте контроллера, Request - это DTO, который определяет, какие параметры должен содержать запрос, и инкапсулирует в себе процесс валидации.

Для работы команды указываем имя:

~$ php bitrix.php make:request CreatePost

Module id: my.module
List of fields separated `,`:
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Infrastructure/Controller/Request/CreatePostRequest.php

При генерации можно сразу же указать поля объекта через опцию --fields:

php bitrix.php make:request CreatePost -n -m my.module --fields title,description,postingDate

В результате мы получим следующий объект:

<?php

namespace My\Module\Infrastructure\Controller\Request;

final class CreatePostRequest
{
	public function __construct(
		public readonly ?string $title,
		public readonly ?string $description,
		public readonly ?string $postingDate,

	)
	{}

	public static function createFromRequest(\Bitrix\Main\Request $request): self
	{
		return new self(
			$request->get('title'),
			$request->get('description'),
			$request->get('postingDate'),

		);
	}
}

make:service

Сервис - это класс, который инкапсулирует в себе логику приложения.

Для создания севиса указываем имя:

~$ php bitrix.php make:service MyPost
Module id: my.module
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Public/Service/MyPostService.php

make:entity

Сущность — это любой объект бизнес-логики, который необходим при реализации проекта/сайта.

Для создания сущности указываем ее имя:

~$ php bitrix.php make:entity post

Module id: my.module
List of fields separated `,`:
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Internals/Entity/Post.php

При генерации можно сразу же указать поля сущности через опцию --fields:

php bitrix.php make:entity post -n -m my.module --fields title,description,author,createdAt,updatedAt

make:tablet

Таблет — это основной класс при работе ORM, который описывает поля и связи конкретной таблицы. Подробнее можно узнать... где бы вы думали?

Именно! В документации ;-)

При запуске команды нужно указать имя таблицы и имя модуля, после чего будет сгенерирован объект DataManager:

php bitrix.php make:tablet my_post my.module

make:event

Событие — это действие или изменение состояния системы, которое позволяет другим элементам системы реагировать. За деталями снова идём в документацию.

При запуске команды указываем имя создаваемого события:

~$ php bitrix.php make:event PostCreated

Module id: my.module
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Public/Event/PostCreatedEvent.php

make:eventhandler

Обработчик события — это класс, который содержит необходимую реакцию на событие системы. Подробнее можно узнать из документации.

Для создания обработчика указываем имя:

~$ php bitrix.php make:eventhandler PostCreated

Module id for handler: my.module
Module id for handled event: my.module
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Internals/Integration/My/Module/EventHandler/PostCreatedEventHandler.php

При генерации обработчика мы должны указывать 2 модуля: тот, который генерирует событие, и тот, который будет содержать обработчик события. Это необходимо для корректного формирования файловой структуры. Допустима ситуация как в примере выше, когда и событие, и обработчик находятся в одном и том же модуле.

make:message

Сообщение — это DTO, который содержит в себе полезную нагрузку для обработчика. По сути своей очень похожи на события, разница лишь в механике обработки — через брокера сообщений. Узнать о сообщениях подробнее можно из документации.

Минимально нужно указать имя:

~$ php bitrix.php make:message PostCreated
Module id: my.module
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Public/Message/PostCreatedMessage.php

make:messagehandler

Обработчик сообщения — это класс, который содержит необходимую логику для обработки сообщения. Подробнее об обработчиках сообщений — в документации.

При вызове команды можно указать только имя:

~$ php bitrix.php make:messagehandler PostCreated
Module id for handler: my.module
Module id for handled message: my.module
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Internals/Integration/My/Module/MessageHandler/PostCreatedMessageHandler.php

При генерации обработчика мы должны указывать 2 модуля: тот, который генерирует событие, и тот, который будет содержать обработчик события. Это необходимо для корректного формирования файловой структуры. Допустима ситуация как в примере выше, когда и событие, и обработчик находятся в одном и том же модуле.

make:agent

Агенты — это периодические задачи или скрипты, которые выполняются по расписанию. Узнать подробнее о них можно из документации.

Для создания агента указываем его имя:

~$ php bitrix.php make:agent MyAgent

Module id: my.module
Prefix for the standard namespace for the generated class:
Namespace of context for the generated class:

A file has been created:
/app/public/portal/local/modules/my.module/lib/Infrastructure/Agent/MyAgentAgent.php

PHP code for register agent:
\CAgent::AddAgent(
    '\My\Module\Infrastructure\Agent\MyAgentAgent::run();',
    'my.module',
    period: 'N',
    interval: 60,
    next_exec: \ConvertTimeStamp(time(), 'FULL')
);

messenger:consume

Данная команда запускает обработку сообщений, находящихся в данный момент в очереди. Прежде чем запускать команду, необходимо сконфигурировать брокер сообщений для работы в режиме CLI. Узнать об этом подробнее можно из документации.

Для запуска никаких аргументов указывать не нужно, обработка очередей запустится в бесконечном режиме и будет обрабатывать сообщения с паузой в 1 секунду между проходами (не сообщениями):

~$ php bitrix.php messenger:consume

Started 2025-11-24 04:31:47. PID: 3772

Если нужно обработать только конкретные очереди, то можно передать первый аргумент команды:

php bitrix.php messenger:consume first_queue,second_queue,third

Если нужно указать другой таймаут между проходами, то можно передать опцию --sleep:

php bitrix.php messenger:consume --sleep 11

Если нужно ограничить время работы обработчика, то можно передать опцию --time-limit или -t:

php bitrix.php messenger:consume -t 600

orm:annotate

При работе с ORM активно используются генерируемые классы и магические методы. Чтобы IDE могла подсказывать существующие классы и методы, нужно сгенерировать аннотации: докблоки, которые вместо реального кода будут содержать сигнатуры методов.

Чтобы сгенерировать аннотации, можно просто запустить команду, опустив все аргументы и опции:

php bitrix.php orm:annotate

Тогда будут сформированы аннотации для модуля main и сохранены в файл bitrix/modules/orm_annotations.php.

Если нужно сохранить итоговый файл в конкретное место, нужно указать первый аргумент команды:

php bitrix.php orm:annotate ../my_annotate.php

В случае если указан относительный путь, то он будет вычисляться от текущей директории. Если указан абсолютный путь, то по указанному маршруту и будет создан файл.

Если нужно сгенерировать аннотации для нескольких модулей, можно указать их имена через запятую:

php bitrix.php orm:annotate /home/folder/my_annotate.php -m main,iblock,crm,im

Можно указать значение all, тогда аннотации будут сгенерированы для всех модулей системы:

php bitrix.php orm:annotate /home/folder/my_annotate.php -m all

Если нужно сгенрировать аннотации для конкретного модуля и поместить их в директорию с самим модулем, что будет актуально для разработчиков модулей, нужно использовать опцию --inside:

php bitrix.php orm:annotate /home/folder/my_annotate.php -m my.module --inside

ВАЖНО: данная опция работает только при указании одного модуля.

Если нужно перегенировать все аннотации, то можно использовать опцию --clean (по умолчанию существующие аннотации не переписываются):

php bitrix.php orm:annotate /home/folder/my_annotate.php --clean

update

Команды из данной категории используются для работы с системой обновлений текущего проекта. Это альтернативный способ обновления сайта не через интерфейс админки, с дополнительным функционалом.

update:modules

Данная команда выполняет обновление модулей.

Если нужно обновить все модули, можно запускать команду без аргументов и опций:

php bitrix.php update:modules

Если нужно установить конкретные модули, то можно использовать опцию --modules или -m для перечисления нужных через запятую:

php bitrix.php update:modules -m main,iblock,ui

После запуска команды может возникнуть ситуация, когда список обновляемых модулей больше чем то, что указано при вызове команды. Это необходимые зависимости для обновления указанных модулей, т.е. без установки дополнительных модулей не получится обновить нужные.

ВАЖНО: команда без подтверждения устанавливать ничего не будет! Сначала будет показано, что планируется выполнить, и будет запрошено подтверждение, а только потом запустится непосредственно само выполнение.

update:versions

Данная команда выполняет обновление модулей для указанных версий.

Перед запуском вам необходимо сформировать JSON-файл со списком модулей и их версий, например, такой:

{
	"main": "25.700.0",
	"sender": "25.100.0",
	"pull": "25.200.100",
	"rest": "25.700.100",
	"ui": "25.500.0",
	"iblock": "25.0.200",
	"mobileapp": "25.0.0",
	"perfmon": "25.100.0",
	"bitrixcloud": "25.0.0",
	"clouds": "25.100.0",
	"security": "24.100.0",
	"messageservice": "25.0.0",
	"socialservices": "25.100.0",
	"fileman": "25.100.0"
}

При запуске команды нужно будет указать расположение данного файла:

php bitrix.php update:versions ~/bitrix_modules_versions.json

И после запуска будет сформирован список конкретных версий, которые должны будут установиться. После запуска команды может возникнуть ситуация, когда список обновляемых модулей больше чем то, что указано при вызове команды. Это необходимые зависимости для обновления указанных модулей, т.е. без установки дополнительных модулей не получится обновить нужные.

ВАЖНО: команда без подтверждения устанавливать ничего не будет! Сначала будет показано, что планируется выполнить, и будет запрошено подтверждение, а только потом запустится непосредственно само выполнение.

update:languages

Данная команда выполняет обновление языковых файлов.

Если нужно обновить все языковые файлы, можно запускать команду без аргументов и опций:

php bitrix.php update:languages

Если нужно установить конкретные языки, то можно использовать опцию -l для перечисления нужных через запятую:

php bitrix.php update:languages -l it

# или
php bitrix.php update:languages -l it,br,tr

После выполнения вам будет показан список доступных языковых пакетов.

ВАЖНО: команда без подтверждения устанавливать ничего не будет! Сначала будет показано, что планируется выполнить, и будет запрошено подтверждение, а только потом запустится непосредственно само выполнение.

Итоги

Мы обсудили команды, которые есть в поставке системы, и то, как их можно использовать. В следующий раз поговорим о том, как добавить свои команды, чтобы они работали так же как и встроенные, через единую точку входа bitrix.php.

Пишите в комментариях свои предложения по работе уже существующих команд, какие стоит добавить в стандартную поставку для решения рутиных задач, которые приходится выполнять регулярно через интерфейс или свои наработки (например очистка кеша), и делитесь опытом работы и использования CLI в рамках работы с Битрикс.

Список команд представленный в статье, актуален на момент публикации статьи! Найти актуальную информацию по CLI-командам, фреймворку и продукту, вы можете в нашей официальной документации: docs.1c-bitrix.ru.