---
title: 使用 CLI
url: https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/using
description: ant CLI 的命令結構、輸出格式、GJSON 轉換、請求主體與除錯。
---

本頁涵蓋 `ant` CLI 適用於每個端點的輸入與輸出機制。若要安裝與驗證，請參閱[快速入門](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/quickstart)。若要串接命令並對資源進行版本控制，請參閱 [CLI 腳本與自動化](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/scripting)。

## 命令結構

命令遵循 `resource action` 模式。巢狀資源使用冒號：

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

執行 `ant --help` 以取得完整的資源清單，或在任何子命令後附加 `--help` 以查看其旗標。

處於 beta 階段的資源（包括 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/zh-TW/cli-sdks-libraries/cli/authentication#switch-between-workspaces)。                                                                                                                                                                     |
| `--format`                           | 輸出格式：`auto`、`json`、`jsonl`、`yaml`、`pretty`、`raw`、`explore`                                                                                                                                                                                                                                                                          |
| `--transform`                        | 使用 [GJSON 路徑](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/using#transform-output-with-gjson)篩選或重塑回應                                                                                                                                                                                                               |
| `-r`、`--raw-output`                  | 列印字串結果時不加上外圍引號，如同 `jq -r`                                                                                                                                                                                                                                                                                                           |
| `--base-url`                         | 覆寫 API 基礎 URL                                                                                                                                                                                                                                                                                                                       |
| `--workspace-id`                     | 選用。要作為 `anthropic-workspace-id` 標頭傳送的工作區 ID（`wrkspc_...`），適用於可存取多個工作區的 API 金鑰（等同於設定 `ANTHROPIC_WORKSPACE_ID`）。請參閱[選擇工作區](https://platform.claude.com/docs/zh-TW/manage-claude/authentication#select-a-workspace)。[Admin API](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api) 命令有其自己的 `--workspace-id`，用於指定其所管理的工作區。 |
| `--debug`                            | 將完整的 HTTP 請求與回應列印至 stderr                                                                                                                                                                                                                                                                                                           |
| `--format-error`、`--transform-error` | 與 `--format` 和 `--transform` 相同，但套用於[錯誤回應](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/scripting#inspect-errors)                                                                                                                                                                                                  |

## 輸出格式

`auto` 會美化列印 JSON，並且是建立或修改資源之命令的預設值。列出與擷取命令在寫入終端機時預設使用[互動式瀏覽器](https://platform.claude.com/docs/zh-TW/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` 篩選器。

### 互動式瀏覽器

此瀏覽器是一個可摺疊與搜尋的「text-based user interface」（文字使用者介面），即 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 引號的情況下列印，可直接指派給 shell 變數：

```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` 會移除字串結果的 JSON 引號，如同 `jq -r`。`--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/zh-TW/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
```

在結構化旗標值內，請將路徑以引號包住。若要將 PDF 傳送至 Messages API：

```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`）。

## 除錯

在任何命令加上 `--debug`，即可將確切的 HTTP 請求與回應（標頭與主體）列印至 stderr。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/zh-TW/api/cli/messages/create)中。若要在本機列出，請執行 `ant --help`，並在任何子命令後附加 `--help` 以查看其旗標與參數。

## 後續步驟

<CardGroup cols={3}>
  <Card title="CLI 腳本與自動化" icon="code" href="https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/scripting">
    對 API 資源進行版本控制、腳本模式，以及從 Claude Code 使用
  </Card>

  <Card title="API 參考文件" icon="book" href="https://platform.claude.com/docs/zh-TW/api/cli/messages/create">
    端點專屬的參數、請求欄位與回應結構描述
  </Card>

  <Card title="CLI 驗證選項" icon="lock" href="https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/authentication">
    API 金鑰、無頭主機、多個工作區與具名設定檔
  </Card>
</CardGroup>