Архитектура CLI: API-клиент и команды приложения

Если действие уже доступно через подходящий API, внутренний CLI для него обычно не нужен. Другая программа вызывает API через SDK или HTTP-клиент. Оператору, CI или агенту можно дать CLI-клиент того же API, если он упрощает повторяемые команды, авторизацию и вывод. Сервер выполняет операцию в обоих случаях.

Внутренняя команда нужна, когда операцию обоснованно выполняют в окружении приложения без его HTTP API: миграция данных, восстановление или обслуживание, для которого нет подходящего поддерживаемого API. Она загружает код и конфигурацию приложения и вызывает прикладной сценарий. Запуск на той же машине сам по себе ничего не определяет: клиент API может работать там же, а внутренняя команда — в отдельном контейнере.

Поэтому сначала выбирают путь выполнения операции: API или код приложения напрямую. Затем, для пути через API, решают, достаточно ли SDK/HTTP-клиента или нужен удобный CLI. Ниже — порядок выбора, примеры и основания из Microsoft Learn и документации действующих проектов.

Порядок выбора

API — программный интерфейс, CLI — интерфейс командной строки, SDK — библиотека для работы из кода. В этой статье под API понимается сетевой контракт приложения, обычно HTTP. API задаёт программный контракт операции, а CLI — способ обращения из терминала; CLI может вызывать API. Поддерживаемый API также может быть административным, доступным только во внутренней сети и только уполномоченным операторам.

1. Есть подходящий API для этой операции? Если он даёт нужный результат, полномочия, объём и гарантии, используйте его. Если операция должна стать удалённой возможностью продукта, проектируйте подходящий API, а не выдавайте пользователю доступ к моделям и базе.
2. Кто будет обращаться к этому API? Для другой программы обычно достаточно SDK или HTTP-клиента. Для повторяемой работы в терминале, shell-сценария, CI или агента оцените CLI-клиент.
3. Почему API не подходит? Если это миграция, ремонт или внутренняя процедура с доступом к коду, данным и инфраструктуре приложения, рассмотрите поддерживаемую внутреннюю команду. Зафиксируйте конкретное ограничение API; слово «административная» само по себе не основание.
4. Штатного пути нет, а вмешательство действительно разовое? Допустим ограниченный скрипт с проверками и планом восстановления. Повторное использование — повод оформить поддерживаемый инструмент.

Когда API достаточно

Если сервис интеграции должен получить заказ и обновить его статус, он может вызвать API из своего кода. SDK помогает работать с типами, авторизацией и ответами; без подходящего SDK можно использовать HTTP-клиент. Схема: программа → SDK/HTTP-клиент → API → прикладной сценарий → данные. Собственный CLI здесь не добавляет новой возможности серверу.

Не стоит по умолчанию встраивать вызов CLI-процесса внутрь другого приложения. Тогда придётся дополнительно поддерживать установку бинарного файла, quoting аргументов, окружение, разбор stdout/stderr и коды завершения. CLI из программы допустим, когда это штатный контракт инструмента или он уже реализует нужный сложный сценарий; это отдельное решение, а не обязательный слой доступа к API.

Когда нужен CLI поверх API

CLI полезен, если человек или автоматизация повторяет один сценарий и каждый раз вручную собирает HTTP-запросы. Например, команда получения статуса задания может выбрать профиль, выполнить вход, пройти страницы ответа и вернуть стабильный JSON. Путь остаётся прежним: оператор/CI/агент → CLI → API → прикладной сценарий → данные. Базу и внутренний код приложения на машине клиента устанавливать не нужно.

Разрабатывать такой клиент стоит при повторяемой потребности и готовности поддерживать его контракт. Если достаточно готового SDK, существующего CLI или нескольких документированных запросов, отдельная оболочка необязательна. Одна команда может вызывать несколько endpoint; CLI вправе собирать результат, но сервер остаётся владельцем правил операции. Не следует имитировать единую транзакцию нескольких запросов, если сервер такой гарантии не предоставляет.

Когда выбирать внутреннюю команду

Внутренняя команда оправданна, если для конкретной процедуры нужен запуск кода приложения без HTTP: например, миграция между версиями схемы, восстановление производного индекса или проверка внутренней целостности, которые не предоставлены как поддерживаемые API-операции. Путь: оператор → команда приложения → прикладной сценарий → данные. Это отдельная точка входа в приложение, обычно отдельный процесс, а не команда, исполняемая внутри уже работающего web-процесса.

Прямой путь экономит транспорт, позволяет управлять порциями, блокировками и транзакциями в пределах возможностей хранилища. Цена — доступ к окружению, совместимость с релизом и большая ответственность за полномочия. Если то же обслуживание уже поддерживается административным API, сначала оцените этот API: создавать внутренний обход только ради названия «обслуживание» не нужно.

Если продукт изначально работает только локально или как пакетное приложение, CLI может быть его основным входом и выполнять обычные прикладные операции напрямую. HTTP API ради самой консоли не обязателен. Обсуждаемое разделение особенно важно, когда у системы уже есть удалённые пользователи, интеграции и отдельные эксплуатационные процедуры.

«В окружении приложения» не означает «обязательно на той же машине»

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

Обратный пример: CLI на сервере приложения отправляет запрос на https://api.example.com или http://localhost. Он всё равно клиент API, потому что проходит HTTP-контракт. И наоборот, запуск через SSH может стартовать внутреннюю команду: SSH переносит команду оператора, но не превращает вызов кода приложения в продуктовый API.

Куда вынести общую логику

HTTP-обработчик и внутренняя команда разбирают свой ввод и передают его одному прикладному сценарию там, где операция совпадает. Сценарий загружает данные, вызывает доменную модель, сохраняет результат и координирует аудит. Бизнес-инварианты остаются в доменной модели; например, отгруженный заказ нельзя отменить из любого интерфейса. Транзакции и внешние события требуют участия инфраструктуры.

Команда не должна копировать правила из контроллера или напрямую менять ORM-модель в обход необходимых проверок. Схема запуска может различаться: web-host и console-host собирают зависимости отдельно. Для административной процедуры допустим отдельный сценарий и политика доступа; общая логика не означает одинаковые полномочия для пользователя и оператора. Это применение Service Layer ↗ и портов и адаптеров ↗. Рекомендации Microsoft по Clean Architecture ↗ отделяют прикладное ядро от UI и инфраструктуры; использование этого ядра из двух точек входа — наш вывод из такого разделения, а не отдельное предписание Microsoft о CLI.

Как подготовить внутреннюю команду

• Определить точную операцию, допустимые цели, объём и результат; назвать ограничение существующего API
• Запускать совместимый релиз и явно выбирать окружение, чтобы не смешать production и тестовые данные
• Передавать контекст оператора и применять административную политику, ограничения выборки и аудит
• Для изменений разделять предварительный просмотр и применение с повторной проверкой состояния
• Задать размер порций, точку продолжения, зависимости, условия остановки и восстановление

На схеме ниже сравниваются два вида консольных команд. Программа, которая использует API без CLI, обращается к тому же HTTP API через SDK или HTTP-клиент.

До реализации соберите API-контракт и эксплуатационные процедуры, роли, объёмы, ограничения зависимостей и требования к повторам. На выходе согласуйте решение по таблице «Что должно получиться на выходе» ниже.

Пример: отмена заказа и восстановление индекса

Рассмотрим условную систему продаж. У неё есть поддерживаемый API заказов; доступ для интеграции и оператора выдан раздельно. API восстановления индекса пока нет. Эти допущения определяют выбор, а не названия команд.

Что делать, если HTTP недоступен

Внешний CLI, SDK и прямой HTTP-запрос не восстановят недоступный API: это разные клиенты одного пути. Внутренняя команда может помочь, если сломан именно web-слой, а её собственные зависимости доступны. Если недоступна база, очередь или сервис авторизации, нужный этой команде, отсутствие HTTP не решит проблему.

Аварийный путь нужно спроектировать и проверить заранее: разрешённые операции, доступ оператора, журнал, совместимость релиза и восстановление. Недоступность HTTP сама по себе не разрешает прямую запись в базу и обход проверок. Если такой команды нет, сначала диагностируйте отказ; не считайте произвольный SQL эквивалентом штатного сценария.

Большая операция не обязана обходить API

Удалённый клиент может отправить запрос на запуск задания, получить его идентификатор и проверять статус. Тяжёлая работа выполняется серверным worker, а не удерживается в одном HTTP-запросе. Microsoft описывает Asynchronous Request-Reply ↗ с ответом о принятой работе и отдельным ресурсом состояния. Поэтому тайм-аут обычного endpoint — повод проверить пакетную или фоновую модель, а не автоматическое основание для внутреннего CLI.

Выбор внутренней команды остаётся обоснованным для процедуры, которую организация намеренно выполняет только в эксплуатационном окружении. Если её нужно регулярно запускать удалённо с контролируемыми правами, может быть уместен административный API, запускающий тот же фоновый сценарий.

Полномочия и аудит

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

Предварительный просмотр и конфликт

Покажите точные идентификаторы и предполагаемые изменения. Между preview и apply данные могут измениться: при применении заново проверьте условия, версии записей и допустимый объём. Старый preview не является разрешением изменить любое новое состояние.

Повтор после сбоя

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

Транзакции и внешние эффекты

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

Пакеты и восстановление

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

Рекомендации Microsoft, Google и AWS

Ниже разделены конкретные рекомендации и наблюдаемая практика продуктов. Это основания для выбора, а не единый корпоративный стандарт «всегда использовать CLI» или «всегда использовать API». Документация проверена 11 октября 2026 года; дата проверки не означает дату публикации каждой страницы.

У Microsoft также есть Azure Developer CLI (azd) ↗ для повторяемых этапов разработки и развёртывания. Это пример ценности составного рабочего сценария: полезная команда может объединять локальные действия и обращения к сервисам, а не только копировать один endpoint.

Как это устроено в популярных open source проектах

В российской облачной практике Selectel описывает OpenStack CLI как клиент API ↗, а Yandex Cloud предоставляет CLI для управления облачными ресурсами ↗. Это дополнительные примеры консольного управления удалённой системой; они не требуют устанавливать её серверный код у оператора.

Статьи и инженерные мнения 2025–2026 годов

• Microsoft: Versioning policy for Azure services, SDKs, and CLI tools ↗ — на странице указано обновление 12 декабря 2025 года. Полезна для поддержки совместимости клиентов; это документация, а не сравнительный эксперимент
• Cloudflare: Building a CLI for all of Cloudflare, 13 апреля 2026 ↗ — авторы описывают генерацию интерфейсов и составные локальные/API-сценарии. Показанная в статье версия cf — technical preview на момент публикации, не универсальный образец готовности
• Arcjet: Designing a CLI for AI agents, 2 июня 2026 ↗ — API остаётся границей контракта, CLI и MCP используют общую продуктовую модель. Структурированный вывод, ошибки и подтверждения помогают агентам; сервер всё равно проверяет права
• Fern: How to build a CLI for your API, 6 июля 2026 ↗ — аргументы за генерацию CLI из спецификации API, чтобы уменьшить расхождение команд и endpoint. Это позиция поставщика генератора; составные сценарии и удобство команд нужно оценивать отдельно
• Яндекс: MCP vs CLI + Skill, 16 июня 2026 ↗ — в эксперименте сравнивают способы работы агента с внутренними API. Результат зависит от сценария, загрузки описаний и формы ответа; он не доказывает общего превосходства CLI над MCP

Совместный вывод этих источников: поддерживаемый API может обслуживать SDK, CLI и MCP, а внутренние команды остаются отдельным инструментом эксплуатации. Наш порядок выбора выше — синтез этих практик. В приведённых источниках нет обязательной для всех приложений трёхчастной классификации CLI.

Что регулируют стандарты

Единого стандарта выбора между API, CLI-клиентом и внутренней командой нет. Ниже — спецификации и рекомендации для отдельных частей решения. Они не определяют место запуска и не требуют создавать CLI поверх любого API.

Для CLI отдельно зафиксируйте аргументы, машинный JSON-вывод, stderr, коды завершения, неинтерактивный вход и правила совместимости. Проверки на стороне клиента улучшают обратную связь, но не заменяют серверную авторизацию. Command Line Interface Guidelines — практические рекомендации, не обязательный отраслевой стандарт.

Запишите решение так, чтобы другой разработчик понял причину: «Для ERP используем API через SDK; отдельный CLI не нужен. Для оператора поддерживаем CLI того же API. Для восстановления индекса используем внутреннюю команду, потому что API запуска этой процедуры нет». Для каждой операции назовите ограничения, при изменении которых выбор нужно пересмотреть.

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

Как проверить рабочий результат

• Одинаковые правила операции. Изменение сценария проверяется в одном прикладном слое; консоль и интеграции не создают параллельную реализацию правил продукта.
• Контролируемое обслуживание. У ремонтных команд есть отдельные полномочия и журнал действий; административные возможности не приходится открывать всем клиентам.
• Защита от ошибочного повтора. Проверки состояния, границы пакета и защита от повторов проверены на сценариях сбоя. Сам по себе выбор CLI не гарантирует уменьшения риска.

Нужно ли сначала делать API для любой команды?

Нет. Локальной обработке файлов, миграции или внутренней процедуре API может быть не нужен. API нужен, когда операцию решено предоставлять как контролируемую удалённую возможность. Если подходящий API уже есть, для SDK или CLI-клиента используйте его.

Если CLI запускается на том же сервере, он внутренний?

Только если вызывает код и сервисы приложения напрямую. Запрос CLI к localhost проходит API и остаётся клиентским путём. Физическое место запуска не определяет архитектуру.

Может ли CLI обращаться прямо к базе?

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

Что выбрать для AI-агента: CLI, API или MCP?

Проверьте доступный агенту интерфейс, права, предсказуемость входа и результата. Готовый MCP-инструмент или API может быть достаточен. CLI полезен, когда агент умеет работать с терминалом и команда уменьшает число ручных шагов; давать ему серверное окружение ради обычного API-действия не требуется. Для повторяемой работы опишите процедуру в Skill (SKILL.md): входы, команды, проверки и остановку. Skill может использовать CLI, API или MCP; технические полномочия ограничивает исполняющая система.

Выберите одну операцию и проверьте существующий API: даёт ли он нужный результат и гарантии? Если да, определите, достаточно ли SDK/HTTP-клиента или повторяемая работа оправдывает CLI. Если нет, запишите конкретную причину для внутренней команды, её окружение и административные ограничения.

Для проверки прав используйте практику проверки авторизации API. Границы внешнего контракта и эксплуатационные процедуры поможет описать документация интеграционного проекта. Если API, консоль и скрипты уже меняют одни данные по разным правилам, это предмет аудита кода и архитектуры.