# echolot flow (/ko/docs/cli/flow)

`echolot flow`는 앱 없이 [플로](/docs/flows)를 실행합니다. 터미널이나 CI 작업에서 한 번 실행하거나, 예약된 플로를 때가 되면 실행하고
웹훅에 응답하는 서비스로 실행합니다.

| 하위 명령 | 동작 |
| --- | --- |
| `echolot flow list` | 작업 공간의 플로를 입력과 문제와 함께 나열합니다. |
| `echolot flow run` | 플로를 실행하고, 블록이 끝날 때마다 출력한 다음 플로의 출력을 출력합니다. |
| `echolot flow new` | 비어 있거나 템플릿으로 만든 플로를 생성합니다. 이름이 없으면 템플릿을 나열합니다. |
| `echolot flow serve` | 중지할 때까지 예약된 플로를 때가 되면 실행하고 웹훅에 응답합니다. |

모든 하위 명령은 `-w` 또는 `--workspace`로 작업 공간을 받습니다.

## echolot flow list [#echolot-flow-list]

```sh
echolot flow list --workspace <workspace> [--json]
```

```sh
echolot flow list -w Alpenglow.echolot
```

```text
morning-stock-check  Morning stock check
order-status-webhook  Order status on webhook
place-test-order  Place a test order  MCP tool place_test_order
```

각 줄에는 플로의 슬러그(`flows/`에 있는, `.flow.toml`을 뺀 파일 이름)와 이름이 있고, 해당하는 경우 괄호 안의 입력(선택 입력은 대괄호),
플로가 제공되는 MCP 도구, 문제의 수가 이어집니다. `--json`은 각 플로를 `slug`, `name`, `description`, `inputs`, `blockCount`,
`errors`, `warnings`, 그리고 `schedule` 또는 `webhook`과 함께 출력합니다.

## echolot flow run [#echolot-flow-run]

```sh
echolot flow run <flow> --workspace <workspace> [--env <env>] [--input <name=value> ...] [--json] [--no-input]
```

`<flow>`는 플로의 슬러그 또는 이름입니다.

```sh
echolot flow run morning-stock-check -w Alpenglow.echolot
```

```text
✓ start  Start  0 ms
✓ list  List products  148 ms
✓ low  Running low?  4 ms
notification: Restock Bern — A tent is under five in Bern.
✓ notify  Restock  0 ms
Morning stock check: passed in 152 ms
```

- 각 블록은 끝날 때 한 줄을 출력합니다. `✓` 또는 `✗`, 블록 ID, 제목, 소요 시간이며, 실패했으면 오류도 함께 표시됩니다. **로그** 블록이
  쓴 내용과 각 테스트의 결과는 별도의 줄로 이어집니다.
- 알림은 표준 오류로 나갑니다.
- 플로의 출력은 마지막에 JSON으로 출력되고, 요약이 표준 오류로 이어집니다.
- `--input name=value`는 입력을 설정합니다. 텍스트가 입력의 타입으로 변환됩니다. 입력마다 한 번씩 지정합니다.
- 플로에 사람이 필요하면(값이 없는 입력, **승인** 블록) Echolot이 터미널에서 묻습니다. `--no-input`은 절대 묻지 않고 그 지점에서 플로를
  실패시키며, CI에서는 이쪽을 원할 것입니다.
- `--json`은 진행 줄 대신 실행 기록 전체를 JSON으로 출력합니다.

```sh
echolot flow run "Place a test order" -w Alpenglow.echolot --env staging --no-input
```

| 옵션 | 의미 |
| --- | --- |
| `-w`, `--workspace <folder>` | 작업 공간 폴더. 필수입니다. |
| `--env <env>` | 플로의 요청이 사용하는 환경: `.toml`을 뺀 파일 이름 또는 이름. |
| `--input <name=value>` | 입력. 텍스트가 입력의 타입으로 변환됩니다. 반복할 수 있습니다. |
| `--json` | 진행 상황 대신 실행 기록을 JSON으로 출력합니다. |
| `--no-input` | 절대 묻지 않습니다. 사람이 필요한 플로는 그 지점에서 실패합니다. |

플로가 실패하거나 플로의 테스트 중 하나가 실패하면 실행이 실패하며 1로 종료합니다.

## echolot flow new [#echolot-flow-new]

```sh
echolot flow new [<name>] [--workspace <workspace>] [--template <template>]
```

이름이 없으면 템플릿을 나열합니다.

```text
device-sign-in  OAuth device sign-in: shows the code and link (with a QR code), waits until the person approves, saves the tokens to the Keychain.
refresh-token  Trades the refresh token for a new access token and saves both to the Keychain; says so when it fails.
paginate-and-export  Fetches a number of pages, gathers their items into one list and writes it to a JSON file in the workspace.
smoke-monitor  Every hour, checks that a request answers 200 quickly; a notification when it does not.
seed-and-clean-up  Creates a few records, leaves room for what needs them, then deletes each one again.
```

이름을 주면 새 플로 파일을 씁니다.

```sh
echolot flow new "Export tents" --template paginate-and-export -w Alpenglow.echolot
```

```text
Created flows/export-tents.flow.toml.
```

템플릿은 요청을 비워 두므로 앱이나 플로 파일에서 직접 고릅니다. 캔버스의 메모가 어느 요청인지 알려 줍니다.
[템플릿](/docs/flows/templates)을 참조하십시오.

| 옵션 | 의미 |
| --- | --- |
| `-w`, `--workspace <folder>` | 작업 공간 폴더. |
| `--template <template>` | 시작할 템플릿: `device-sign-in`, `refresh-token`, `paginate-and-export`, `smoke-monitor`, `seed-and-clean-up`. 없으면 플로가 비어 있습니다. |

## echolot flow serve [#echolot-flow-serve]

```sh
echolot flow serve --workspace <workspace> [--env <env>] [--port <port>] [--share] [--token <token>]
```

일정이 있는 모든 플로를 때가 되면 실행하고, 웹훅이 있는 플로의 웹훅에 응답합니다. <kbd>⌃</kbd><kbd>C</kbd>로 중지할 때까지 계속됩니다.
서버나 컨테이너에서 실행하면 앱 없이도 작업 공간의 자동화를 계속 유지할 수 있습니다.

```sh
echolot flow serve -w Alpenglow.echolot --port 4100
```

```text
Serving Alpenglow (Ctrl-C stops it)
  schedule  Morning stock check: 0 6 * * *
  webhook   POST http://127.0.0.1:4100/order-status  (Order status on webhook)
  token     3f9a…
```

각 실행은 시각, 플로, 종료 결과, 소요 시간이 있는 한 줄을 출력합니다.

**웹훅.** 호출자는 플로 웹훅의 메서드와 경로로 요청을 보내며, 토큰은 `Authorization: Bearer <token>`, `X-Echolot-Token` 헤더,
URL의 `?token=` 중 하나로 보냅니다. 플로의 입력은 쿼리와 JSON 본문에서 가져옵니다. `body`라는 입력은 본문 전체를 받습니다. 응답은
플로의 출력을 JSON으로 돌려주며, 플로가 실패하면 오류와 함께 `500`, 올바른 토큰이 없으면 `401`, 어떤 플로에도 없는 경로면 있는 경로를
알려 주는 `404`입니다.

```sh
curl -X POST http://127.0.0.1:4100/order-status \
  -H "Authorization: Bearer $ECHOLOT_WEBHOOK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"orderId": "ord_7Hk2Lw"}'
```

토큰은 `--token`, 없으면 `ECHOLOT_WEBHOOK_TOKEN`, 그것도 없으면 Echolot이 출력하는 새 토큰입니다. 웹훅 실행은 최대 2분이 걸릴 수 있으며,
8 MB를 넘는 본문은 통째로 거부됩니다.

| 옵션 | 의미 |
| --- | --- |
| `-w`, `--workspace <folder>` | 작업 공간 폴더. 필수입니다. |
| `--env <env>` | 플로의 요청이 사용하는 환경. |
| `--port <port>` | 웹훅 포트. `0`이면 빈 포트를 고릅니다. 기본값은 4100입니다. |
| `--share` | 이 컴퓨터만이 아니라 모든 네트워크 인터페이스에서 웹훅에 응답합니다. 컨테이너용입니다. |
| `--token <token>` | 웹훅 토큰. 기본값은 `ECHOLOT_WEBHOOK_TOKEN`, 없으면 출력되는 새 토큰입니다. |

앱에서의 일정과 웹훅은 [플로 실행과 트리거](/docs/flows/running-and-triggers)를 참조하십시오.

## 종료 코드 [#exit-codes]

| 코드 | 조건 |
| --- | --- |
| `0` | `run`: 플로가 모든 테스트와 함께 통과했습니다. `list`, `new`: 완료했습니다. |
| `1` | `run`: 플로가 실패했거나 테스트가 실패했습니다. |
| `64` | 잘못된 옵션, 존재하지 않는 플로나 환경, 또는 `name=value` 형식이 아닌 `--input`. |