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 для собственных скриптов.

elemctl is a CLI tool, MCP server and Python library for the 1C:Enterprise.Element (1cmycloud) Console API: manage applications, upload builds and deploy with honest apply verification. Docs are in Russian - the platform’s audience - but the CLI output is plain JSON.

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

Возможности

Приложения: список, карточка, создание, запуск, остановка, удаление, версия технологии, данные для сессии отладки (apps debug).
Проекты и сборки: загрузка .xasm/.xlib, список сборок, удаление.
Сборка из исходников: упаковка каталога проекта (Проект.yaml + модули) в архив сборки с манифестом и git-метаданными, автоинкремент версии.
Деплой одной командой: сборка -> загрузка -> применение -> перезапуск -> проверка фактического применения.
Ветки среды разработки: список, создание, привязка к приложению, merge.
Дампы: создание и контроль готовности.
MCP-сервер: те же операции как инструменты для AI-агентов (Claude Code и другие MCP-клиенты).
Плагины: точки расширения (importlib.metadata) - внешний пакет приносит debug-адаптер платформы (elemctl debug-adapter), не раздувая ядро.
Обновление: elemctl self-update - обновить пакет распаковкой колеса, даже когда elemctl.exe занят работающим MCP-сервером (штатный pipx/pip в этом случае ломает установку).
Расширение VS Code (отладка): спутник в editors/vscode – отладка приложений 1С:Предприятие.Элемент (XBSL) в обычном VS Code через штатный debug-адаптер платформы; координаты debug-сессии берёт через elemctl apps debug.

Честная проверка применения

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

задачи приложения со статусом Error/Failed, начатые после старта деплоя (старые ошибки из истории не учитываются);
фактическую версию проекта приложения (source.project-version) - она должна совпасть с только что загруженной сборкой;
доступность 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}
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

# данные для сессии отладки: {"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 branches merge <branch-id>

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

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

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

Инструмент неофициальный и не аффилирован с фирмой “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 - ходить за причиной в журнал сервера не нужно.
Удалённые приложения остаются в списке платформы со статусом 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 нет, она выполняется в консоли управления.