---
referenceVersion: 2
---

# Запуск команд

`cli` запускает установленный инструмент, например jq или CLI модели.

## Параметры

| Параметр | Назначение | По умолчанию |
| --- | --- | --- |
| `command` | Список аргументов команды | Обязательно |
| `stdin` / `stdin_json` / `stdin_file` | Один способ передать вход | Не задан |
| `cwd` | Рабочий каталог процесса | Каталог исполнителя |
| `max_output_bytes` | Максимум stdout + stderr одной попытки | 8388608 |
| `env` | Изменения окружения; null удаляет переменную | {} |
| `parse` | text, raw, json | text |
| `json_mode` | strict или extract, для JSON | strict |
| `timeout_seconds` | Лимит всех попыток и пауз | 300 |
| `retry` | max_attempts, when_stderr_matches, delay_seconds=0, backoff=1 | Выключен |
| `required_secrets` | Требуемые секреты | [] |

Команда передаётся аргументами, не shell-строкой. Секреты передаются явно через `env`/`stdin`.

## Пример

```yaml [Фрагмент формата v2]
- id: active
  block: cli
  params:
    command: [jq, '-c', '{{items: [.[] | select(.active == true)]}}']
    stdin_json: "{inputs.records}"
    parse: json
    timeout_seconds: 30
```

Команда использует установленный `jq`; результат читается через `{active.json.items}`.

## Результат

```json
{"text": "stdout", "json": {"answer": 42}, "exit_code": 0}
```

`raw` сохраняет текст буквально, `text` убирает внешние пробелы и кодовую ограду. В режиме `json` исходный вывод остаётся в `text`, разобранное значение — в `json`.

**Изменение:** сейчас JSON-поля смешиваются с результатом блока. Предлагается отдельное поле: `{generate.json.answer}`.

## Поведение

Ненулевой код, превышение времени или невалидный JSON завершают шаг. `extract` разрешает извлечение JSON из обрамляющего текста; `strict` требует только JSON. Повторы задаются явно, максимум 10 попыток.

## Использование

Оркестрация остаётся в workflow: вызов модели → проверка → исправление → согласование. Собственный скрипт, который скрыто выполняет всю цепочку, эту модель нарушает. CLI работает с правами процесса и не является изоляцией чужого кода.

## Начальный охват

Базового набора достаточно для вызова существующих инструментов: аргументы, три способа ввода, окружение, текстовый или JSON-результат, таймаут и явные повторы. Нужность каждого следующего параметра проверяет разработчик на конкретном сценарии. Новые возможности добавляем совместимо; удаление и смена смысла требуют миграции.

<span id="решения-по-параметрам"></span>

## Параметры операций

Используются argv-список, взаимно исключающие `stdin`/`stdin_json`/`stdin_file`, окружение и явные повторы: они нужны текущим сценариям. `cwd` нужен инструментам с рабочим каталогом. `max_output_bytes` ограничивает накопление вывода во время чтения процесса; обрезанный JSON не считается успешным результатом. В текущем исполнителе такого лимита ещё нет.

`parse` и `json_mode` имеют разные обязанности: первое выбирает формат, второе — строгость разбора JSON. Не объединяем их в неявные эвристики. JSON в отдельном поле поддерживает объекты, массивы и скаляры без конфликта с `text`/`exit_code`. stderr остаётся диагностикой ошибки, а не новым обязательным полем результата.

<span id="модули-и-поставка"></span>

## Плагины и установка

В составе блока: Процессы, argv, stdin, env, cwd, файлы, stdout/stderr и разбор результата.

| Плагин | Возможности |
| --- | --- |
| — | Отдельных плагинов для CLI-инструментов нет |

jq, FFmpeg и CLI моделей поставляются окружением приложения. Пакет блока не устанавливает эти программы.