---
title: CLI 사용하기
url: https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/using
description: ant CLI의 명령 구조, 출력 형식, GJSON 변환, 요청 본문 및 디버깅에 대해 설명합니다.
---

이 페이지에서는 모든 엔드포인트에 공통으로 적용되는 `ant` CLI의 입력 및 출력 메커니즘을 다룹니다. 설치 및 인증 방법은 [빠른 시작](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/quickstart)을 참조하세요. 명령을 연결하고 리소스를 버전 관리하는 방법은 [CLI 스크립팅 및 자동화](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/scripting)를 참조하세요.

## 명령 구조

명령은 `resource action` 패턴을 따릅니다. 중첩된 리소스는 콜론을 사용합니다:

```text wrap
ant <resource>[:<subresource>] <action> [flags]
```

전체 리소스 목록을 보려면 `ant --help`를 실행하고, 하위 명령의 플래그를 보려면 해당 하위 명령에 `--help`를 추가하세요.

베타 상태의 리소스(agents, sessions, deployments, environments 포함)는 `beta:` 접두사 아래에 있습니다. 이 네임스페이스의 명령은 해당 리소스에 적합한 `anthropic-beta` 헤더를 자동으로 전송하므로 직접 전달할 필요가 없습니다. `--beta <header>`는 기본값을 재정의할 때만 사용하세요(예: 다른 스키마 버전을 선택하는 경우).

```bash
ant models list
ant messages create --model claude-opus-5-5 --max-tokens 1024 ...
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...
```

### 전역 플래그

| 플래그                                   | 설명                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile`                           | 이번 호출에 사용할 명명된 프로필입니다(`ANTHROPIC_PROFILE` 설정과 동일). [워크스페이스 간 전환](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/authentication#switch-between-workspaces)을 참조하세요.                                                                                                                                                                                                          |
| `--api-key-stdin`                     | 표준 입력에서 API 키를 읽습니다. 이 플래그는 표준 입력 전체를 읽으므로 요청 본문은 [플래그](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/using#flags)로 전달하세요.                                                                                                                                                                                                                                                |
| `--auth-token-stdin`                  | 표준 입력에서 bearer 토큰을 읽습니다. 이 플래그는 표준 입력 전체를 읽으므로 요청 본문은 [플래그](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/using#flags)로 전달하세요.                                                                                                                                                                                                                                            |
| `--format`                            | 출력 형식: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore`                                                                                                                                                                                                                                                                                                                     |
| `--transform`                         | [GJSON 경로](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/using#transform-output-with-gjson)로 응답을 필터링하거나 재구성합니다                                                                                                                                                                                                                                                            |
| `-r`, `--raw-output`                  | `jq -r`처럼 문자열 결과를 따옴표 없이 출력합니다                                                                                                                                                                                                                                                                                                                                                         |
| `--base-url`                          | API 기본 URL을 재정의합니다                                                                                                                                                                                                                                                                                                                                                                     |
| `--workspace-id`                      | 선택 사항입니다. 여러 워크스페이스에 접근할 수 있는 API 키의 경우 `anthropic-workspace-id` 헤더로 전송할 워크스페이스 ID(`wrkspc_...`)입니다(`ANTHROPIC_WORKSPACE_ID` 설정과 동일). [워크스페이스 선택](https://platform.claude.com/docs/ko/manage-claude/authentication#select-a-workspace)을 참조하세요. [Admin API](https://platform.claude.com/docs/ko/manage-claude/admin-api) 명령은 자체 `--workspace-id`를 받으며, 이는 대신 해당 명령이 관리하는 워크스페이스를 지정합니다. |
| `--debug`                             | 전체 HTTP 요청 및 응답을 stderr에 출력합니다                                                                                                                                                                                                                                                                                                                                                         |
| `--format-error`, `--transform-error` | `--format` 및 `--transform`과 동일하지만 [오류 응답](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/scripting#inspect-errors)에 적용됩니다                                                                                                                                                                                                                                                  |

## 출력 형식

`auto`는 JSON을 보기 좋게 출력하며, 리소스를 생성하거나 수정하는 명령의 기본값입니다. 목록 및 조회 명령은 터미널에 출력할 때는 [대화형 탐색기](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/using#interactive-explorer)를, 파이프로 연결될 때는 보기 좋게 출력된 JSON을 기본값으로 사용합니다. `--format`으로 두 기본값 모두 재정의할 수 있습니다:

```bash
ant models retrieve --model-id claude-opus-5-5 --format yaml
```

```yaml Output
type: model
id: claude-opus-5-5
display_name: Claude Opus 5.5
created_at: "2026-09-22T00:00:00Z"
...
```

목록 엔드포인트는 자동으로 페이지를 넘깁니다. 기본 형식에서는 각 항목이 개별적으로 출력되므로(`jsonl` 모드에서는 한 줄에 하나의 압축된 JSON 객체, `yaml` 모드에서는 YAML 문서 스트림) `head`, `grep` 및 `--transform` 필터로 깔끔하게 스트리밍됩니다.

### 대화형 탐색기

탐색기는 큰 응답을 탐색하기 위한 접기 및 검색 기능을 갖춘 TUI입니다. 화살표 키로 노드를 펼치고 접으며, `/`로 검색하고, `q`로 종료합니다. 목록 및 조회 명령은 터미널에 연결되어 있을 때 기본적으로 탐색기를 엽니다. 명시적으로 열려면 `--format explore`를 전달하세요:

```bash
ant models list --format explore
```

## GJSON으로 출력 변환하기

출력하기 전에 응답을 재구성하려면 `--transform`을 사용하세요. 표현식은 [GJSON 경로](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)입니다. 목록 엔드포인트의 경우 변환은 엔벨로프가 아닌 각 항목에 개별적으로 실행됩니다:

```bash
ant beta:agents list \
  --transform "{id,name,model}" \
  --format jsonl
```

```jsonl Output
{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-opus-5-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5-5"}
```

### 스칼라 값 추출하기

단일 필드를 따옴표 없는 문자열로 가져오려면(예: 새로 생성된 리소스의 ID) `--transform`과 `--raw-output`을 함께 사용하세요. 결과는 JSON 따옴표 없이 출력되며 셸 변수에 바로 할당할 수 있습니다:

```bash
AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-opus-5-5}' \
  --transform id --raw-output)
```

<Note>
  `--raw-output`은 `--format raw`와 다릅니다. `--raw-output`은 `jq -r`처럼 문자열 결과에서 JSON 따옴표를 제거합니다. `--format raw`는 자동 페이지 넘김 없이 응답 본문의 원시 JSON 바이트를 출력하며, 목록 엔드포인트에서는 `--transform`을 각 항목이 아닌 페이지네이션 엔벨로프에 적용합니다.
</Note>

## 요청 본문 전달하기

적절한 입력 방식은 데이터의 형태에 따라 다릅니다. 스칼라 필드와 짧은 구조화된 값에는 **플래그**를 사용하고, 중첩되거나 여러 줄로 된 본문에는 **stdin** 문서를 파이프로 전달하며, 문자열 또는 바이너리 필드에 파일 내용을 가져오려면 **`@file` 참조**를 사용하세요.

### 플래그

스칼라 필드는 플래그에 직접 매핑됩니다. 구조화된 필드는 완화된 YAML 유사 구문(따옴표 없는 키, 문자열 주위의 선택적 따옴표) 또는 엄격한 JSON을 허용합니다:

```bash
ant beta:sessions create \
  --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "CLI docs test session"
```

반복 가능한 플래그는 배열을 만듭니다. 각 `--tool` 또는 `--event`는 요소 하나를 추가합니다:

```bash
ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-5-5}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'
```

### Stdin

전체 요청 본문을 제공하려면 JSON 또는 YAML 문서를 stdin으로 파이프하세요. stdin의 필드는 플래그와 병합되며, 플래그가 우선합니다. 여기서 `version`은 이전 `retrieve`에서 반환된 낙관적 잠금 토큰이며, `$AGENT_ID`는 [스칼라 값 추출하기](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/using#extract-a-scalar)에서와 같이 가져온 값입니다:

```bash
echo '{"description": "Updated test agent.", "version": 1}' | \
  ant beta:agents update --agent-id "$AGENT_ID"
```

Heredoc도 같은 방식으로 작동하며 여러 줄 YAML에 편리합니다. 본문 내부의 변수 확장을 비활성화하려면 구분자를 따옴표로 감싸세요(`<<'YAML'`처럼).

```bash
ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-5-5
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML
```

### 파일 참조

업로드 명령의 `--file`처럼 파일 경로를 받는 플래그는 경로를 그대로 받습니다:

```bash
ant files upload --file ./report.pdf
```

파일 내용을 문자열 값 필드에 인라인으로 넣으려면 경로 앞에 `@`를 붙이세요:

```bash
ant beta:agents create \
  --name "Researcher" --model '{id: claude-opus-5-5}' \
  --system @./prompts/researcher.txt
```

구조화된 플래그 값 내부에서는 경로를 따옴표로 감싸세요. Messages API에 PDF를 보내려면 다음과 같이 합니다:

```bash
ant messages create \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: [
    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
    {type: text, text: "Extract the text from this scanned document."}
  ]}'
```

CLI는 파일 유형을 감지하고 바이너리 파일을 자동으로 base64로 인코딩합니다. 특정 인코딩을 강제하려면 일반 텍스트에는 `@file://`을, base64에는 `@data://`를 사용하세요. 리터럴로 시작하는 `@`는 백슬래시로 이스케이프하세요(`\@username`).

## 디버깅

정확한 HTTP 요청 및 응답(헤더와 본문)을 stderr에 출력하려면 아무 명령에나 `--debug`를 추가하세요. API 키는 가려집니다.

```bash
ant --debug beta:agents list
```

```text Output wrap
GET /v1/agents?beta=true HTTP/1.1
Host: api.anthropic.com
Anthropic-Beta: managed-agents-2026-04-01
Anthropic-Version: 2026-10-21
Authorization: Bearer <REDACTED>
...
```

## 사용 가능한 리소스

CLI가 제공하는 모든 API 리소스는 [API 레퍼런스](https://platform.claude.com/docs/ko/api/cli/messages/create)에 문서화되어 있습니다. 로컬에서 목록을 보려면 `ant --help`를 실행하고, 하위 명령의 플래그와 매개변수를 보려면 해당 하위 명령에 `--help`를 추가하세요.

## 다음 단계

<CardGroup cols={3}>
  <Card title="CLI 스크립팅 및 자동화" icon="code" href="https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/scripting">
    API 리소스 버전 관리, 스크립팅 패턴 및 Claude Code에서의 사용
  </Card>

  <Card title="API 레퍼런스" icon="book" href="https://platform.claude.com/docs/ko/api/cli/messages/create">
    엔드포인트별 매개변수, 요청 필드 및 응답 스키마
  </Card>

  <Card title="CLI 인증 옵션" icon="lock" href="https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/authentication">
    API 키, 헤드리스 호스트, 여러 워크스페이스 및 명명된 프로필
  </Card>
</CardGroup>