---
title: CLI 腳本與自動化
url: https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/scripting
description: 使用 ant apply 將 API 資源以檔案形式進行版本控制、在指令碼中串接 ant CLI 命令、從 Claude Code 操作資源，以及使用 CLI 憑證驗證 curl 呼叫。
---

本頁涵蓋以 `ant` CLI 為基礎的任務導向工作流程。關於底層旗標與輸出選項，請參閱[使用 CLI](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/using)。

## 對 API 資源進行版本控制

若要將代理、環境及其他 Claude Managed Agents 資源以檔案形式保存在您的儲存庫中，請參閱[使用 ant apply 以程式碼管理資源](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/apply)。

### 從 shell 執行已套用的代理

代理與環境建立後，您就可以從 shell 驅動一個「session」（工作階段）：

<Steps>
  <Step title="啟動工作階段">
    將代理 ID 與環境 ID 傳遞給工作階段建立命令。執行 `ant apply` 後，請從 `claude-lock.json` 讀取這些 ID：`resources` 下的每個項目都有一個 `id`，而對於[使用 ant apply 以程式碼管理資源](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/apply)中的專案，這些項目為 `./agents/summarizer.md` 與 `./environments/cloud.yaml`。

    ```bash
    ant beta:sessions create \
      --agent agent_011CYm1BLqPXpQRk5khsSXrs \
      --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
      --title "Summarization task"
    ```

    ```json Output
    {
      "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
      "status": "running"
      /* ... */
    }
    ```
  </Step>

  <Step title="傳送使用者訊息">
    將先前輸出中的 session `id` 複製到 `--session-id`：

    ```bash
    ant beta:sessions:events send \
      --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
      --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}'
    ```
  </Step>

  <Step title="讀取對話">
    代理回覆後，列出事件。`--transform` 會針對每個列出的事件執行，因此這會依序印出每則訊息的文字。`--format auto` 會覆寫列表命令在終端機中預設開啟的互動式瀏覽器：

    ```bash
    ant beta:sessions:events list \
      --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
      --transform 'content.0.text' \
      --raw-output \
      --format auto
    ```

    ```text Output wrap
    Summarize the benefits of type safety in one sentence.
    Type safety catches errors at compile time rather than runtime, reducing bugs, improving code clarity, enabling better tooling support, and making codebases easier to maintain and refactor with confidence.
    ```

    <Tip>
      若要在工作階段執行時即時觀看，請使用 `ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K --format jsonl`，它會在每個事件抵達時將其寫入 stdout。若未指定 `--format`，終端機會改為開啟互動式瀏覽器。
    </Tip>
  </Step>
</Steps>

## 腳本模式

CLI 的設計可與標準 shell 工具組合使用。

### 將 list 輸出串接至第二個指令

在 list 端點上使用 `--transform id --raw-output` 會每行輸出一個純 ID，因此 `head` 與 `xargs` 等標準工具可直接套用。擷取第一個結果，然後將其傳遞給後續指令：

```bash
FIRST_AGENT=$(ant beta:agents list --transform id --raw-output | head -1)

ant beta:agents:versions list \
  --agent-id "$FIRST_AGENT" \
  --transform "{version,created_at}" --format jsonl
```

### 檢視錯誤

`--transform-error` 與 `--format-error` 旗標會對錯誤回應套用相同的篩選。`--raw-output` 不適用於錯誤，因此請使用 `--format-error yaml` 以取得不帶引號的純量值。僅擷取錯誤訊息：

```bash
ant beta:agents retrieve --agent-id bogus \
  --transform-error error.message --format-error yaml 2>&1
```

```text Output wrap
GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found
Agent not found.
```

## 從 Claude Code 使用 CLI

[Claude Code](https://code.claude.com/docs/zh-TW/overview) 可直接使用 `ant` CLI。在 CLI 已安裝並完成驗證後，您可以要求 Claude Code 直接操作您的 API 資源。例如：

* 「列出我最近的 agent sessions，並摘要說明哪些發生了錯誤。」
* 「將 `./reports` 中的每個 PDF 上傳至 Files API，並印出產生的 ID。」
* 「取得 session `session_01...` 的事件，並告訴我 agent 在哪裡卡住了。」

Claude Code 會呼叫 `ant`、解析結構化輸出，並對結果進行推理（無需自訂整合程式碼）。

## 使用 CLI 憑證驗證 curl 請求

使用 `curl` 或其他 HTTP 用戶端呼叫 API 的腳本，可以使用 [`ant auth login`](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/quickstart#authentication) 所儲存的憑證，而非靜態 API 金鑰。OAuth 存取權杖應以 bearer token 的形式放入 `Authorization` 標頭；`x-api-key` 標頭僅用於靜態 API 金鑰。

`ant auth print-credentials --access-token` 會印出目前使用中設定檔的存取權杖，若權杖已過期或即將過期，會先進行更新：

```bash cURL
curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "hi"}]
  }'
```

<Note>
  透過 CLI 登入進行操作時，請保持 `ANTHROPIC_API_KEY` 與 `ANTHROPIC_AUTH_TOKEN` 未設定。對於 `ant` 指令，這兩個變數中的任一個都會優先於登入憑證（請參閱[憑證優先順序](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#credential-precedence)），並可能在不知不覺中將指令導向不同的組織或工作區。
</Note>

執行 [`ant auth status`](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/authentication#check-authentication-status) 以確認您登入的組織與工作區；當有環境變數覆寫您的登入時，它會發出警告。