# Инструмент командной строки (/ru/docs/cli)

`echolot` запускает из терминала или задания CI то, что вы создаёте в приложении: отправляет запросы, прогоняет рабочее
пространство вместе с проверками и пишет отчёты, импортирует и экспортирует коллекции, проверяет спецификации линтером,
поднимает моки, запускает сценарии и обслуживает рабочее пространство для ИИ-агентов по MCP. Он читает те же файлы
рабочего пространства, что и приложение, поэтому ничего не нужно конвертировать.

## Установите инструмент командной строки [#get-the-command-line-tool]

<Tabs items={["В приложении", "Zip со страницы релизов"]}>
  <Tab value="В приложении">
    В версии с прямой загрузкой инструмент лежит внутри приложения. Чтобы добавить его в `PATH`:

    1. Выберите **Echolot › Установить инструмент командной строки…** или откройте **Настройки › Основные** и нажмите
       **Установить инструмент командной строки…** в разделе **Инструмент командной строки**.
    2. Echolot помещает в `/opt/homebrew/bin` или `/usr/local/bin` ссылку `echolot` на инструмент внутри приложения.
       Если ни одна из папок недоступна для записи, macOS просит пароль администратора.
    3. Откройте новое окно Терминала и введите `echolot --help`.

    **Настройки › Основные › Инструмент командной строки** показывает, где лежит встроенный инструмент и ссылка в вашем
    `PATH`. Нажмите **Переустановить**, когда вы переместили приложение, и **Удалить**, чтобы убрать ссылку. Если
    на пути стоит файл `echolot`, который Echolot туда не клал, Echolot спрашивает, прежде чем его заменить, и файл
    попадает в Корзину.

    Поскольку ссылка указывает внутрь приложения, инструмент обновляется вместе с приложением.

    <Shot id="cli-settings-command-line-tool" alt="Настройки, панель «Основные», раздел «Инструмент командной строки» с путём к встроенному инструменту и ссылкой в вашем PATH" />
  </Tab>
  <Tab value="Zip со страницы релизов">
    У каждого релиза есть отдельный инструмент, `echolot-<version>-macos.zip`, на
    [странице релизов](https://github.com/staticdreams/echolot-public/releases). В нём один файл, `echolot`,
    подписанный и нотаризованный, как приложение. Распакуйте его и переместите в папку из `PATH`:

    ```sh
    unzip echolot-0.5.0-macos.zip
    sudo mv echolot /usr/local/bin/
    echolot --version
    ```

    Используйте zip на Mac без приложения, на раннере CI или с версией из App Store.
  </Tab>
</Tabs>

<Edition only="appstore">
  В версии из App Store внутри нет инструмента и нет пункта **Установить инструмент командной строки…**. Вместо этого
  установите инструмент из zip на странице релизов. Он работает с теми же рабочими пространствами.
</Edition>

Срок действия инструмента командной строки не истекает, в том числе в бета-сборках приложения. Ему нужна macOS 15 или
новее на Mac.

## Команды [#commands]

| Команда | Что делает |
| --- | --- |
| [`echolot send`](/docs/cli/send) | Отправляет один запрос, URL или сохранённый файл запроса, и пишет тело в стандартный вывод. |
| [`echolot run`](/docs/cli/run) | Прогоняет рабочее пространство, некоторые его папки или запросы либо коллекцию Postman, с проверками и отчётами. |
| [`echolot validate`](/docs/cli/validate) | Проверяет, что каждый файл рабочего пространства читается и каждый запрос разрешается. |
| [`echolot import`, `echolot export`](/docs/cli/import-export) | Загружает коллекции в рабочее пространство и записывает рабочее пространство как Postman, Insomnia, Bruno или Echolot. |
| [`echolot mcp`](/docs/cli/mcp) | Проверяет MCP-серверы, входит в них, обслуживает рабочее пространство для агентов и печатает настройки клиентов. |
| [`echolot spec`](/docs/cli/spec) | Проверяет документы OpenAPI линтером, а также проверяет и применяет изменения спецификации к папке, которая за ней следует. |
| [`echolot graphql diff`](/docs/cli/graphql) | Сравнивает две схемы GraphQL и оценивает каждое изменение. |
| [`echolot grpc`](/docs/cli/grpc) | Описывает сервисы gRPC и вызывает их методы. |
| [`echolot mqtt`](/docs/cli/mqtt) | Подписывается на брокеры MQTT и публикует в них. |
| [`echolot mock`](/docs/cli/mock) | Поднимает мок: маршруты мока рабочего пространства или документ OpenAPI. |
| [`echolot fake`](/docs/cli/fake) | Создаёт тестовые данные по шаблону, для фикстур и начальных данных. |
| [`echolot flow`](/docs/cli/flow) | Перечисляет, запускает, создаёт и обслуживает сценарии рабочего пространства. |
| [`echolot agent`](/docs/cli/agent) | Запускает встроенного агента на задачу, с политикой вместо одобрений. |

`echolot help <command>` и `echolot <command> --help` печатают все параметры команды. Команды с подкомандами принимают
их так же: `echolot mcp serve --help`.

## Параметры, которые есть у каждой команды [#options-every-command-has]

| Параметр | Значение |
| --- | --- |
| `--version` | Печатает версию и сборку, например `0.5.0 (8)`. |
| `-h`, `--help` | Печатает параметры команды. |

## Рабочие пространства и окружения [#workspaces-and-environments]

Команды, которые работают с рабочим пространством, принимают его папку — ту, в которой лежит `workspace.toml`. Одни
принимают её аргументом (`echolot run Alpenglow.echolot`), другие через `-w` или `--workspace`
(`echolot flow list -w Alpenglow.echolot`); на странице каждой команды сказано, как именно. Если она необязательна,
используется текущая папка.

`--env` выбирает окружение по имени файла без `.toml` (`staging`). `run`, `validate` и `flow` принимают и его имя
(`Staging`). Без `--env` запросы разрешаются с переменными самого рабочего пространства. См.
[окружения](/docs/workspaces/environments).

## Секреты [#secrets]

Секретные значения никогда не хранятся в файлах рабочего пространства: в файле указано имя секретной переменной и
ничего больше. Инструмент командной строки ищет каждое значение в таком порядке:

1. Переменная окружения `ECHOLOT_SECRET_<NAME>`. Имя — это имя переменной заглавными буквами, где каждый символ, не
   являющийся буквой или цифрой, заменён на `_`: `token` — это `ECHOLOT_SECRET_TOKEN`, `me_password` —
   `ECHOLOT_SECRET_ME_PASSWORD`.
2. Для `echolot run` — файл, указанный в `--secrets`: по одной строке `NAME=value`, `#` для комментариев, кавычки вокруг
   значения снимаются. `NAME` — это имя переменной (`token=…`) или полное имя переменной окружения
   (`ECHOLOT_SECRET_TOKEN=…`). Значения из файла важнее переменных окружения.
3. На Mac — элементы Связки ключей, которые ведёт приложение. Секрет, который вы задали в приложении, или MCP-сервер, в
   который вы вошли, работает и в Терминале.

```sh
export ECHOLOT_SECRET_PASSWORD="$(op read 'op://Shop/Alpenglow staging/password')"
echolot run Alpenglow.echolot --env staging
```

Связка ключей не используется, когда задана `CI` (любым значением, кроме пустого, `0` или `false`) или когда
`ECHOLOT_KEYCHAIN=0`. Так задание CI не будет ждать запроса Связки ключей. См. [секреты](/docs/workspaces/secrets).

## Переменные окружения [#environment-variables]

| Переменная | Кто использует | Значение |
| --- | --- | --- |
| `ECHOLOT_SECRET_<NAME>` | Каждая команда, разрешающая запросы | Значение секретной переменной `<NAME>`. |
| `ECHOLOT_KEYCHAIN=0` | Каждая команда | Не читать и не писать Связку ключей. |
| `CI` | Каждая команда | Если задана, Связка ключей выключена, как с `ECHOLOT_KEYCHAIN=0`. |
| `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY` | `send`, `run`, `mqtt` и другие | Прокси, читаются так же, как их читает curl. `--proxy` и `--no-proxy` их переопределяют; собственная настройка прокси рабочего пространства приоритетнее. |
| `ECHOLOT_CERT_PASSPHRASE` | `send`, `run`, `mqtt` | Парольная фраза ключа или файла PKCS#12, указанных в `--cert` или `--key`. |
| `ECHOLOT_MQTT_PASSWORD` | `mqtt` | Пароль брокера. |
| `ECHOLOT_MCP_TOKEN` | `mcp serve --http` | Bearer-токен, который отправляют клиенты; иначе случайный. |
| `ECHOLOT_WEBHOOK_TOKEN` | `flow serve` | Токен, который отправляют вызывающие вебхуки; иначе случайный. |
| `ECHOLOT_BROWSER` | `mcp sign-in` | Команда, которая открывает страницу входа вместо браузера по умолчанию. |
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` | `agent` | API-ключ провайдера модели. |
| `NO_COLOR` | `run` | Простой вывод в консоль. |

## Вывод и коды выхода [#output-and-exit-codes]

Результаты идут в стандартный вывод: тело ответа, отчёт, строки, которые печатает подписка. Ход выполнения,
предупреждения, результаты тестов и время идут в стандартный поток ошибок, так что вывод можно передавать дальше по
конвейеру:

```sh
echolot send https://demo.echolot.dev/v1/products/TNT-MH-2P | jq .name
```

| Код выхода | Значение |
| --- | --- |
| `0` | Всё сработало, и все проверки прошли. |
| `1` | Что-то не удалось: нет ответа, непройденная проверка или тест, найдены проблемы (`validate`, `spec lint`), несовместимые изменения (`graphql diff`), статус gRPC, отличный от OK, отклонённое подключение MQTT, агент, который не завершил работу. |
| `22` | Только `echolot send`: статус ответа 400 или выше, как с `curl --fail`. |
| `64` | Сама командная строка неверна: неизвестный параметр, отсутствующий файл, несуществующее окружение. Причина печатается. |

## Дальше [#next]

- [Прогон рабочего пространства](/docs/cli/run) и [запуск в CI](/docs/cli/ci).
- [Обслуживание рабочего пространства для агентов](/docs/cli/mcp).
- [Тестирование API в CI](/docs/tutorials/test-in-ci) — учебник.