elemctl

Утилита командной строки, 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.

Возможности

• Приложения: список, карточка, создание, запуск, остановка, удаление, версия технологии.
• Проекты и сборки: загрузка .xasm/.xlib, список сборок, удаление.
• Сборка из исходников: упаковка каталога проекта (Проект.yaml + модули) в архив сборки с манифестом и git-метаданными, автоинкремент версии.
• Деплой одной командой: сборка -> загрузка -> применение -> перезапуск -> проверка фактического применения.
• Ветки среды разработки: список, создание, привязка к приложению, merge.
• Дампы: создание и контроль готовности.
• MCP-сервер: те же операции как инструменты для AI-агентов (Claude Code и другие MCP-клиенты).

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

Особенность платформы: если применение проекта падает, платформа молча откатывает приложение на предыдущую сборку - статус 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 не имеют внешних зависимостей (только стандартная библиотека).

Настройка

Реквизиты подключения берутся из переменных окружения либо из .env в текущем каталоге (переменные окружения имеют приоритет):

Переменная	Назначение
ELEMENT_BASE_URL	базовый URL платформы, например https://1cmycloud.com
ELEMENT_CLIENT_ID	Client-Id для получения токена
ELEMENT_CLIENT_SECRET	Client-Secret
ELEMENT_APP_ID	приложение по умолчанию (необязательно)
ELEMENT_PROJECT_ID	проект по умолчанию (необязательно)
ELEMENT_SPACE_ID	пространство по умолчанию (необязательно)

Client-Id/Client-Secret выпускаются в панели управления 1cmycloud (раздел интеграций Console API). Шаблон файла - .env.example.

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

# список приложений
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

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

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

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

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

MCP-сервер

Сервер отдаёт операции платформы как MCP-инструменты (транспорт stdio):

pip install "elemctl[mcp]"
claude mcp add elemctl -- elemctl mcp

Реквизиты подключения сервер берёт из тех же переменных ELEMENT_* / .env. Среди инструментов: list_apps, get_app, deploy (с полем ok в ответе), verify_deploy, list_builds, merge_branch и другие.

Использование как библиотеки

from elemctl import Config, ElementClient
from elemctl.deploy import deploy_from_sources

client = ElementClient(Config.from_env())
apps = client.list_apps()

report = deploy_from_sources(
    client,
    app_id="...",
    project_id="...",
    project_dir="acme/crm",
    log=print,
)
assert report.ok, report.problems

Формат сборки

.xasm (приложение) и .xlib (библиотека) - это ZIP-архив:

Assembly.yaml            # манифест: ProjectKind, Vendor, Name, Version, ...
{vendor}/{name}/...      # файлы проекта: .yaml, .xbsl, ресурсы

Каталог проекта должен лежать по схеме {repo}/{vendor}/{name}/Проект.yaml - пути в архиве строятся относительно корня репозитория. Вид проекта (приложение/библиотека) определяется по полю ВидПроекта в Проект.yaml.

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

• Инструмент неофициальный и не аффилирован с фирмой "1С"; Console API может меняться без предупреждения.
• Используется только документированный Console API v2 - внутренние API консоли платформы инструмент не вызывает и не описывает.
• Создание приложения только по --project-id на части конфигураций платформы даёт пустой каркас без данных проекта. Надёжный путь - источник-сборка: elemctl apps create <имя> --project-id <id> --latest-build (MCP-инструмент create_app подставляет последнюю сборку автоматически), а после создания - elemctl deploy.
• Удалённые приложения остаются в списке платформы со статусом 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 нет, она выполняется в консоли управления.

Происхождение и правовые заметки

Код написан с нуля по спецификации внешнего интерфейса платформы - процесс и гарантии описаны в ORIGIN.md. Товарные знаки и отсутствие аффилиации с фирмой "1С" - в файле NOTICE.

Лицензия

MIT