Elemctl

CLI, MCP-сервер и библиотека для Console API 1С:Элемента: приложения, сборки из исходников, развёртывание одной командой с проверкой, что изменение применилось, и пробник, который компилирует исходники на сервере, не трогая рабочее приложение.

Утилита командной строки, MCP-сервер и Python-библиотека для управления приложениями облачной платформы 1С:Предприятие.Элемент (1cmycloud.com) через Console API v2.

elemctl ведёт приложение на платформе весь его срок жизни, и веб-консоль для этого не нужна. Он создаёт приложение, собирает архив .xasm/.xlib из исходников проекта, загружает сборку и применяет её к приложению. Дальше он проверяет, что применение и правда случилось: платформа умеет молча откатить. Компиляцию проверяет пробник, который рабочее приложение не трогает. Отдельные команды ведут ветки среды разработки, дампы и версию технологии.

Движок один, а обратиться к нему можно тремя способами: командой elemctl из терминала и CI, MCP-сервером для AI-агентов (Claude Code и другие MCP-клиенты), python-модулем elemctl из своих скриптов.

Заметки о разработке и новости – в Telegram-канале 1С × ИИ: инженерный цех.

Возможности

• Приложения: список, карточка, создание, запуск, остановка, удаление, версия технологии, данные для сессии отладки (apps debug), сборка, на которой работает приложение, и сборка примененного расширения в файл (apps export, а apps export-extension – из Console API 2.1). Список умеет фильтровать по имени на стороне клиента и показывать краткие карточки по --brief. Команды, адресующие одно приложение, принимают его ид либо точное имя.
• Проекты и сборки: загрузка .xasm/.xlib, список сборок, удаление.
• Сборка из исходников: elemctl упаковывает каталог проекта в архив сборки с манифестом и git-метаданными. В каталоге лежат Проект.yaml и модули. Версию он берёт из флага, из счётчика последней сборки или из номера запуска CI в окружении: CI_PIPELINE_IID, GITHUB_RUN_NUMBER, BUILD_NUMBER. Её же возвращает поле вывода. Дескриптор с английскими написаниями ключей Name/Vendor/Version читается наравне с русским. Приложение, библиотека и расширение собираются одинаково, а расширение получает ту версию манифеста, по которой сервер читает расширения.
• Развёртывание одной командой: сборка -> загрузка -> применение -> перезапуск -> проверка фактического применения. Незакоммиченные изменения каталога проекта видны в отчёте полем dirty. Ключ --require-clean останавливает работу, когда дерево грязное.
• Проверка компиляции без риска для приложения (elemctl probe): исходники компилирует сервер, и делает он это в одноразовом приложении. Ошибки приходят с файлом, строкой и колонкой. Созданное пробник убирает за собой. До рабочего приложения он не дотягивается намеренно: ELEMENT_APP_ID и ELEMENT_PROJECT_ID он не читает.
• Списки пользователей (elemctl user-lists): настройки входа, за которыми обычно ходят в панель управления. Это самостоятельная регистрация и вход по логину с паролем. Список адресуют ид, представлением либо приложением, которому он принадлежит.
• Ветки среды разработки: список, создание, привязка к приложению, слияние.
• Дампы: создание и контроль готовности.
• MCP-сервер: те же операции в виде инструментов для AI-агентов – Claude Code и других MCP-клиентов.
• Плагины: точки расширения importlib.metadata. Внешний пакет приносит debug-адаптер платформы (elemctl debug-adapter) и свои команды, и ядро от этого не раздувается. Одно объявление Command становится сразу и подкомандой CLI, и инструментом MCP. Команда, которая знает про ваше окружение, живёт в вашем пакете, а не в публичном ядре.
• Обновление: elemctl self-update обновляет пакет распаковкой колеса. Это работает и тогда, когда elemctl.exe занят работающим MCP-сервером: штатные pipx и pip в таком случае ломают установку. --stop-holders снимает MCP-серверы, которые держат пакет, а идущие команды других сессий не трогает.
• В VS Code: развёртывание и отладка живут в расширении XBSL. Оно зовёт elemctl: elemctl deploy по кнопке развёртывания, elemctl apps debug за координатами сессии отладки.

Проверка того, что сборка применилась

Особенность платформы: когда применение проекта падает, платформа молча откатывает приложение на предыдущую сборку. Статус Running об успехе при этом ничего не говорит. Поэтому elemctl deploy статусу не верит и после работы проверяет три вещи:

1. Задачи приложения со статусом Error или Failed, начатые после того, как команда взялась за работу. Старые ошибки из истории она пропускает.
2. Фактическую версию проекта приложения, поле source.project-version. Она должна совпасть с только что загруженной сборкой.
3. Доступность uri приложения контрольным HTTP-запросом. Результат идёт в поле uri-status отчёта и ни на что не влияет: у закрытых приложений 401 и 403 нормальны.

Код возврата deploy равен нулю только тогда, когда сборка действительно применилась.

Установка

pipx install elemctl            # или: pip install elemctl
pip install "elemctl[mcp]"      # с MCP-сервером

Нужен Python 3.10 или новее. У ядра и CLI нет внешних зависимостей: только стандартная библиотека.

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

# список приложений
elemctl apps list

# карточка приложения (статус, uri, фактическая версия проекта)
elemctl apps get <app-id>

# создать приложение, только если его ещё нет:
# {"id": ..., "created": true|false, "sign-in": ...} - последнее поле это способ войти
# --wait дожидается приложения И проверяет, на какой сборке оно правда работает
elemctl apps ensure acme-crm-dev --project-id <project-id> --latest-build --wait

# полный цикл деплоя из исходников с проверкой применения
elemctl deploy --app-id <app-id> --project-id <project-id> --project-dir acme/crm

# скомпилировать исходники на сервере, не трогая рабочее приложение:
# ok и ошибки с файлом, строкой и колонкой; за собой убирает
elemctl probe --project-dir acme/crm

# данные для сессии отладки: {"debug-token": ..., "debug-address": ...}
# (нужна включённая отладка на сервере: config/debug.yml enabled: true)
elemctl apps debug <app-id>

# только собрать архив .xasm, никуда не загружая
elemctl build --project-dir acme/crm --output ./dist

# разобрать готовый архив: манифест, подсистемы, глобальные типы с полными именами
elemctl inspect ./dist/e1c-CurrencyConverter-2.0.xlib

# запретить вход по паролю и саморегистрацию в списке пользователей приложения
elemctl user-lists password-login --app crm-dev --disable
elemctl user-lists self-registration --app crm-dev --disable

# принять изменения ветки среды разработки
elemctl branches merge <branch-id>

Все команды пишут JSON в stdout, а прогресс длительных операций – в stderr. Ошибка возвращается JSON-объектом с полем error и кодом возврата 1.

Флаг --json делает это соглашение гарантией для скриптов, и ставить его можно в любой позиции. На время работы команды stdout подменяется на stderr, поэтому в настоящий stdout уходит только JSON ответа. Посторонняя строка туда не попадёт ни из плагина, ни из библиотеки. Читайте поток целиком через json.load, а не ищите в нём первую скобку. Отказ с --json тоже уходит в stderr, и stdout остаётся пустым: текст в машинном канале конвейер принял бы за ответ.

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

apps list и builds list печатают счётчик и отметку об усечении после ответа. У остальных строк в stderr порядок не гарантирован, так что разбирать безопасно только сам stdout, отдельно от stderr.

Полный список команд даёт elemctl --help, по группам – elemctl apps --help, elemctl deploy --help и так далее.

Рядом

• XBSL – всё, что происходит с исходниками до развёртывания: линтер с автоправками, LSP-сервер, заготовки метаданных и расширение VS Code. Кнопка в заголовке редактора запускает оттуда elemctl deploy.
• EDT-Bridge – соседняя платформа: мост MCP внутрь 1С:EDT для конфигураций 1С:Предприятия.

Ограничения и статус

• Инструмент неофициальный, с фирмой “1С” он не связан. Console API может меняться без предупреждения.
• elemctl обращается только к документированному Console API v2. Внутренние API консоли платформы он не вызывает и не описывает.
• На части конфигураций платформы приложение, созданное по одному --project-id, получается пустым каркасом без данных проекта. Надёжнее создавать его от сборки: elemctl apps create <имя> --project-id <id> --latest-build. MCP-инструмент create_app подставляет последнюю сборку сам. После создания идёт elemctl deploy.
• Приложение, созданное со статусом Error, платформа сопровождает общим текстом “Неизвестная ошибка. Обратитесь к администратору”. Подробности лежат в задаче приложения: файлы, строки и колонки ошибок компиляции. apps create --wait и apps ensure печатают их следом за общим текстом, как это давно делают deploy и verify, так что ходить за причиной в журнал сервера не нужно. Статусом Error кончается не всякий сбой: неудачное применение откатывается на прежнюю сборку, и приложение поднимается в статусе Running. Поэтому --wait заодно проверяет, на какой сборке приложение работает на самом деле, и отвечает кодом возврата 1, когда сборка не та, которую просили. Ключ --no-verify возвращает простое ожидание.
• Скомпилировать исходники, ничего не создавая на платформе, нельзя: компиляция серверная и происходит при применении сборки. Для этого и есть probe: он подставляет одноразовое приложение вместо рабочего. Один запуск стоит столько же времени, сколько создание приложения, то есть минуты. Поэтому место ему перед развёртыванием или в CI, а не в цикле “на каждое нажатие”.
• Проект платформы опознается по Ид из Проект.yaml. Сборка, загруженная без ид проекта, попадает в проект с ее Ид, какая бы пара Vendor + Name ни стояла в манифесте, и переименовывает этот проект по себе. builds upload называет этот проект в ответе и предупреждает, если загрузка его переименовала. Пара лишь должна быть свободна: новый Ид с парой, которую уже держит другой проект, платформа отклоняет с 409.
• В только что созданное приложение входят учётной записью панели управления. Приложение получает собственный пустой список пользователей, вход по логину и паролю у него выключен, а сервис учётных записей не подключён. Поэтому учётные записи, которыми входят в другие приложения, здесь не работают. Этого не меняют ни подключение чужого списка пользователей, ни включение локального входа. apps create и apps ensure говорят это сами: поле sign-in в ответе и тот же текст в stderr.
• Удалённые приложения остаются в списке платформы со статусом Deleted и прежним id. На этом id команды apps get и deploy отвечают 404. apps find и apps ensure такие приложения пропускают. Прежний поиск возвращает apps find --include-deleted.
• Приложение с неопубликованными правками в среде разработки платформа удалить не даёт и отвечает HTTP 400 FAILED_PRECONDITION. Принудительного удаления в Console API нет, остаётся панель управления. elemctl подсказывает это в тексте ошибки.
• Если приложение пересоздать, то есть удалить и создать заново, у него сменится URL. Внешние настройки, завязанные на адрес, вроде OIDC redirect, придётся обновить. “Мягкой” очистки данных приложения в Console API нет, её делают в консоли управления.