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С × ИИ: инженерный цех.

Возможности

• Приложения: список (фильтр по имени на клиенте и краткие карточки --brief), карточка, создание, запуск, остановка, удаление, версия технологии, данные для сессии отладки (apps debug). Команды, адресующие одно приложение, принимают его ид либо точное имя.
• Проекты и сборки: загрузка .xasm/.xlib, список сборок, удаление.
• Сборка из исходников: упаковка каталога проекта (Проект.yaml + модули) в архив сборки с манифестом и git-метаданными. Версия - из флага, счётчика последней сборки или номера прогона 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). Список адресуется ид, представлением либо приложением, чей это список.
• Ветки среды разработки: список, создание, привязка к приложению, merge.
• Дампы: создание и контроль готовности.
• MCP-сервер: те же операции как инструменты для AI-агентов (Claude Code и другие MCP-клиенты).
• Плагины: точки расширения (importlib.metadata) - внешний пакет приносит debug-адаптер платформы (elemctl debug-adapter) и собственные команды, не раздувая ядро. Одно объявление Command становится и подкомандой CLI, и инструментом MCP, поэтому команда, знающая про ваше окружение, живёт в вашем пакете, а не в публичном ядре.
• Обновление: elemctl self-update - обновить пакет распаковкой колеса, даже когда elemctl.exe занят работающим MCP-сервером (штатный pipx/pip в этом случае ломает установку).
• В 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": ...} - последнее поле это способ войти
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.

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

Рядом

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

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

• Инструмент неофициальный и не аффилирован с фирмой “1С”; Console API может меняться без предупреждения.
• Используется только документированный 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 - ходить за причиной в журнал сервера не нужно.
• Скомпилировать исходники, ничего не создавая на платформе, нельзя: компиляция серверная и происходит на применении сборки. Ровно для этого есть probe – он подставляет под удар одноразовое приложение вместо рабочего. Прогон стоит столько же, сколько создание приложения (минуты), поэтому его место перед деплоем или в CI, а не в цикле “на каждое нажатие”.
• Проект платформы опознаётся парой Vendor + Name манифеста, а не Ид из Проект.yaml: загрузка сборки без ид проекта попадает в тот проект, которому пара уже принадлежит, а второй проект под ту же пару отклоняется с 409.
• В только что созданное приложение входят учётной записью ПАНЕЛИ УПРАВЛЕНИЯ: оно получает СВОЙ пустой список пользователей, вход по логину и паролю выключен, а сервис учётных записей не подключён, поэтому учётные записи, которыми входят в другие приложения, здесь не работают – и этого не меняют ни подключение чужого списка пользователей, ни включение локального входа. apps create и apps ensure говорят это сами: поле sign-in ответа и то же самое в stderr.
• Удалённые приложения остаются в списке платформы со статусом Deleted и прежним id, на котором apps get и deploy отвечают 404. apps find и apps ensure их пропускают; вернуть прежний поиск - apps find --include-deleted.
• Приложение с неопубликованными правками в среде разработки платформа удалить не даёт (HTTP 400 FAILED_PRECONDITION), принудительного удаления в Console API нет - только через панель управления; elemctl подскажет это в тексте ошибки.
• Пересоздание приложения (delete + create) меняет его URL - внешние настройки, завязанные на адрес (OIDC redirect и т.п.), придётся обновлять. “Мягкой” очистки данных приложения в Console API нет, она выполняется в консоли управления.