# 명령줄 도구 (/ko/docs/cli)

`echolot`은 앱에서 만든 것을 터미널이나 CI 작업에서 실행합니다. 요청을 보내고, 작업 공간을 검사와 함께 실행해 보고서를 작성하고,
컬렉션을 가져오고 내보내고, 명세를 린트하고, 모의 서버를 제공하고, 플로를 실행하고, MCP를 통해 작업 공간을 AI 에이전트에 제공합니다.
앱과 같은 작업 공간 파일을 읽으므로 변환할 필요가 없습니다.

## 명령줄 도구 받기 [#get-the-command-line-tool]

<Tabs items={["앱에서", "릴리스의 Zip"]}>
  <Tab value="앱에서">
    직접 다운로드 버전은 도구를 앱 안에 포함합니다. `PATH`에 추가하려면 다음과 같이 합니다.

    1. <strong>Echolot › 명령줄 도구 설치…</strong>를 선택하거나, <strong>설정 › 일반</strong>을 열고 <strong>명령줄 도구</strong> 아래의 <strong>명령줄 도구
       설치…</strong>를 클릭합니다.
    2. Echolot이 앱 안의 도구를 가리키는 `echolot` 링크를 `/opt/homebrew/bin` 또는 `/usr/local/bin`에 만듭니다. 두 폴더 모두
       쓸 수 없으면 macOS가 관리자 암호를 요청합니다.
    3. 새 터미널 윈도우를 열고 `echolot --help`를 입력합니다.

    <strong>설정 › 일반 › 명령줄 도구</strong>에는 앱에 포함된 도구의 위치와 `PATH`에 있는 링크가 표시됩니다. 앱을 옮긴 뒤에는 <strong>다시 설치</strong>를,
    링크를 없애려면 <strong>제거</strong>를 사용합니다. 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
    ```

    앱이 없는 Mac, CI 러너, App Store 버전에서는 이 zip을 사용합니다.
  </Tab>
</Tabs>

<Edition only="appstore">
  App Store 버전에는 도구가 포함되어 있지 않고 <strong>명령줄 도구 설치…</strong> 항목도 없습니다. 대신 릴리스 페이지의 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` | `--cert` 또는 `--key`로 지정한 키나 PKCS#12 파일의 암호. |
| `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`), OK가 아닌 gRPC 상태, 거부된 MQTT 연결, 끝내지 못한 에이전트 등입니다. |
| `22` | `echolot send` 전용입니다. 응답 상태가 400 이상이었습니다. `curl --fail`과 같습니다. |
| `64` | 명령줄 자체가 잘못되었습니다. 알 수 없는 옵션, 없는 파일, 존재하지 않는 환경 등입니다. 이유가 출력됩니다. |

## 다음 단계 [#next]

- [작업 공간 실행](/docs/cli/run)과 [CI에서 실행](/docs/cli/ci).
- [작업 공간을 에이전트에 제공](/docs/cli/mcp).
- 튜토리얼 [CI에서 API 테스트](/docs/tutorials/test-in-ci).