---
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)을 참조하세요.                                                                                                                                                                                                  |
| `--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을 보기 좋게 출력하며, 리소스를 생성하거나 수정하는 명령의 기본값입니다. 목록 조회(list) 및 단건 조회(retrieve) 명령은 터미널에 출력할 때는 [대화형 탐색기](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)

printf '%s\n' "$AGENT_ID"
```

```text Output wrap
agent_011CYm1BLqPXpQRk5khsSXrs
```

<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`에서 반환된 낙관적 잠금(optimistic-locking) 토큰이며, `$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."}
  ]}' \
  --transform 'content.#(type=="text").text' --raw-output
```

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: 2023-06-01
X-Api-Key: <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>