---
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)。                                                                                                                                                                      |
| `--api-key-stdin`                    | 從標準輸入讀取 API 金鑰。此旗標會讀取所有標準輸入，因此請使用[旗標](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/using#flags)傳遞請求主體。                                                                                                                                                                                                              |
| `--auth-token-stdin`                 | 從標準輸入讀取 bearer token。此旗標會讀取所有標準輸入，因此請使用[旗標](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/using#flags)傳遞請求主體。                                                                                                                                                                                                        |
| `--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` 篩選器。

### 互動式瀏覽器

瀏覽器是一個可摺疊與搜尋的 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)
```

<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."}
  ]}'
```

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: 2026-10-21
Authorization: Bearer <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>