Команды CLI
Пакет содержит одну исполняемую команду — openapi-cli. Она принимает плоский список параметров; подкоманд run / validate / init нет:
openapi-cli [options]
Синтаксис
openapi-cli --spec openapi.json [options]
openapi-cli -c config.json
Спецификация обязательна: передайте --spec (или -s) либо задайте specPath в JSON-файле конфигурации, загружаемом через --config. Остальные параметры необязательны.
Основные параметры
| Параметр | Краткая форма | По умолчанию | Описание |
|---|---|---|---|
--spec <path-or-url> | -s | — | Путь или URL http(s):// к JSON-спецификации OpenAPI 3.2 |
--server <url> | -S | (из спецификации) | Переопределить URL сервера из спецификации |
--output <dir> | -o | ./openapi-cli-report | Каталог для сохранения отчётов |
--format <formats> | -f | json,cli,html | Форматы отчётов через запятую: json, cli, html |
--config <path> | -c | — | Путь к JSON-файлу конфигурации; аргументы CLI имеют приоритет |
Параметры выполнения
| Параметр | Краткая форма | По умолчанию | Описание |
|---|---|---|---|
--concurrency <n> | -n | 5 | Максимум одновременных запросов; целое число от 1 до 100 |
--timeout <ms> | -t | 30000 | Тайм-аут запроса в мс, целое число от 1 до 600000; также используется при загрузке удалённой спецификации |
--no-fail-on-error | — | выключено | После завершённого запуска возвращать 0 даже при провале тестов; ошибки конфигурации и фатальные ошибки по-прежнему приводят к сбою |
Параметры фильтрации
| Параметр | По умолчанию | Описание |
|---|---|---|
--method <methods> | — | HTTP-методы для включения через запятую, например get,post |
--path <patterns> | — | Регулярные выражения через запятую для сопоставления с каждым путём |
--tag <tags> | — | Теги OpenAPI для включения через запятую |
--operation-id <ids> | — | Значения operationId для включения через запятую |
Сеть и TLS
| Параметр | Краткая форма | По умолчанию | Описание |
|---|---|---|---|
--proxy <url> | -p | — | URL HTTP(S)-прокси, например http://proxy.corp:8080 |
--ca <path> | — | — | Набор сертификатов CA в формате PEM |
--cert <path> | — | — | Клиентский сертификат PEM для mTLS |
--key <path> | — | — | Закрытый ключ клиента PEM для mTLS |
--insecure | -k | выключено | Пропустить проверку сертификата TLS |
Аутентификация, заголовки и переменные
| Параметр | Краткая форма | Описание |
|---|---|---|
--header <headers...> | -H | Дополнительные заголовки в виде Key: Value; можно повторять |
--bearer <token> | — | Токен Bearer, отправляемый в заголовке Authorization |
--variable <vars...> | -v | Переменные Postman в виде KEY=VALUE; можно повторять |
--env <path> | — | Путь к файлу .env; существующие переменные окружения не перезаписываются |
Параметры gRPC
| Параметр | По умолчанию | Описание |
|---|---|---|
--grpc-no-reflection | выключено | Отключить рефлексию сервера gRPC и использовать proto-файлы |
--grpc-proto <paths...> | — | Пути к файлам .proto или каталогам, которые их содержат |
Параметры MCP
| Параметр | По умолчанию | Описание |
|---|---|---|
--mcp-transport <transport> | streamable-http | Транспорт MCP: streamable-http или stdio |
--mcp-command <command> | — | Команда MCP stdio, например npx |
--mcp-args <args> | — | Аргументы MCP stdio через пробел или запятую |
--mcp-cwd <dir> | — | Рабочий каталог подпроцесса MCP stdio |
Информационные параметры
| Параметр | Краткая форма | Описание |
|---|---|---|
--help | -h | Показать спр авку |
--version | -V | Показать версию |
Коды завершения
| Код | Значение |
|---|---|
0 | Все тесты пройдены либо задан --no-fail-on-error |
1 | Один или несколько тестов не пройдены или завершились ошибкой, либо не удалось разобрать аргументы CLI |
2 | Ошибка конфигурации, загрузки спецификации или фатальная ошибка выполнения |
Если resolveConfig выбрасывает исключение, например когда не указан ни --spec, ни настроенный specPath, CLI выводит красное сообщение Error: и завершается с кодом 2. Если исключение выбрасывает runTests, выводится Fatal error:, а код завершения также равен 2. После завершённого запуска код 1 возвращается только при report.summary.failed > 0 || report.summary.errors > 0 и failOnError !== false.
Переменные окружения
Специальных переменных OPENAPI_CLI_* нет. Конфигурация задаётся параметрами, файлом конфигурации и следующими механизмами:
- Файл
.env— передайте--env .env, чтобы загрузить парыKEY=VALUEвprocess.env. Существующие переменные не перезаписываются. - Подстановка
${VAR}— после загрузки${VAR_NAME}заменяется вserverUrl,proxy, значенияхheaders,auth.tokenи значенияхvariables.
openapi-cli --spec openapi.json \
--env .env \
--server 'https://${API_HOST}/v1' \
--bearer '${BEARER_TOKEN}'
Примеры запуска
# Test a local spec against its first server URL
openapi-cli --spec openapi.json
# Override the server and write JSON + HTML reports
openapi-cli --spec openapi.json \
--server https://api.staging.example.com \
--format json,html --output ./reports
# Only GET requests, 10 workers, with a bearer token
openapi-cli --spec openapi.json --method get --concurrency 10 --bearer "$TOKEN"
# Use a config file
openapi-cli --config openapi-cli.config.json