CLI、SDK 與函式庫ant CLI

使用 CLI

ant CLI 的命令結構、輸出格式、GJSON 轉換、請求主體與除錯。

本頁涵蓋 ant CLI 適用於所有端點的輸入與輸出機制。關於安裝與驗證，請參閱快速入門。關於串接命令與對資源進行版本控制，請參閱 CLI 腳本與自動化。

命令結構

命令遵循 resource action（資源動作）的模式。巢狀資源使用冒號：

ant <resource>[:<subresource>] <action> [flags]

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

處於測試版的資源（包括 agents、sessions、deployments、environments 和 skills）位於 beta: 前綴之下。此命名空間中的命令會自動為該資源傳送適當的 anthropic-beta 標頭，因此您不需要自行傳遞。僅在需要覆寫預設值時使用 --beta <header>（例如，選擇使用不同的結構描述版本）。

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

全域旗標

旗標	說明
`--profile`	此次呼叫要使用的具名設定檔（等同於設定 `ANTHROPIC_PROFILE`）。請參閱在工作區之間切換。
`--format`	輸出格式：`auto`、`json`、`jsonl`、`yaml`、`pretty`、`raw`、`explore`
`--transform`	使用 GJSON 路徑篩選或重塑回應
`-r`、`--raw-output`	列印字串結果時不加上外圍引號，類似 `jq -r`
`--base-url`	覆寫 API 基礎 URL
`--debug`	將完整的 HTTP 請求與回應列印至 stderr
`--format-error`、`--transform-error`	與 `--format` 和 `--transform` 相同，但套用於錯誤回應

輸出格式

auto 會以美化格式列印 JSON，且是建立或修改資源之命令的預設值。列出與擷取命令在寫入終端機時預設使用互動式瀏覽器，而在透過管線傳輸時則預設為美化格式的 JSON。使用 --format 可覆寫任一預設值：

ant models retrieve --model-id claude-opus-4-8 --format yaml

Output

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00:00:00Z"
...

列出端點會自動分頁。在預設格式中，每個項目會分別寫出（在 jsonl 模式下每行一個精簡的 JSON 物件，在 yaml 模式下則為一連串的 YAML 文件），這能順暢地串流至 head、grep 和 --transform 篩選器。

互動式瀏覽器

此瀏覽器是一個可摺疊與搜尋的 TUI（文字使用者介面），用於瀏覽大型回應。方向鍵可展開與收合節點，/ 可搜尋，q 可退出。列出與擷取命令在連接至終端機時預設會開啟它。傳遞 --format explore 可明確開啟：

ant models list --format explore

使用 GJSON 轉換輸出

使用 --transform 在列印前重塑回應。該運算式是一個 GJSON 路徑。對於列出端點，轉換會針對每個項目個別執行，而非針對外層封裝：

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

Output

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

擷取純量值

若要將單一欄位擷取為不帶引號的字串（例如新建立資源的 ID），請將 --transform 與 --raw-output 搭配使用。結果會在不帶 JSON 引號的情況下列印，可直接指派給 shell 變數：

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-sonnet-4-6}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

Output

agent_011CYm1BLqPXpQRk5khsSXrs

--raw-output 與 --format raw 不同。--raw-output 會從字串結果中去除 JSON 引號，類似 jq -r。--format raw 會列印回應主體的原始 JSON 位元組且不自動分頁；在列出端點上，它會將 --transform 套用於分頁封裝而非每個項目。

傳遞請求主體

正確的輸入機制取決於資料的形態：對於純量欄位和簡短的結構化值使用旗標，對於巢狀或多行主體透過管線傳入 stdin 文件，並使用 @file 參照將檔案內容拉入任何字串或二進位欄位。

旗標

純量欄位直接對應至旗標。結構化欄位接受寬鬆的類 YAML 語法（不加引號的鍵、字串可選擇性加引號）或嚴格的 JSON：

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

可重複的旗標會建立陣列。每個 --tool 或 --event 會附加一個元素：

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-4-8}' \
  --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 則如擷取純量值中所述方式擷取：

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

Heredoc 的運作方式相同，且便於處理多行 YAML。將分隔符號加上引號（如 <<'YAML'）可停用主體內的變數展開。

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

檔案參照

接受檔案路徑的旗標（例如上傳命令的 --file）可接受純路徑：

ant beta:files upload --file ./report.pdf

若要將檔案內容內嵌至字串值欄位，請在路徑前加上 @：

ant beta:agents create \
  --name "Researcher" --model '{id: claude-sonnet-4-6}' \
  --system @./prompts/researcher.txt

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

ant messages create \
  --model claude-opus-4-8 \
  --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.0.text' --raw-output

CLI 會偵測檔案類型並自動將二進位檔案編碼為 base64。若要強制使用特定編碼，請使用 @file:// 表示純文字，或 @data:// 表示 base64。若要表示字面上的開頭 @，請以反斜線跳脫（\@username）。

除錯

在任何命令中加入 --debug，即可將確切的 HTTP 請求與回應（標頭與主體）列印至 stderr。API 金鑰會被遮蔽。

ant --debug beta:agents list

Output

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 參考文件中。若要在本機列出，請執行 ant --help，並在任何子命令後附加 --help 以查看其旗標與參數。

Was this page helpful?

CLI、SDK 與函式庫ant CLI

使用 CLI

ant CLI 的命令結構、輸出格式、GJSON 轉換、請求主體與除錯。

命令結構

命令遵循 resource action（資源動作）的模式。巢狀資源使用冒號：

ant <resource>[:<subresource>] <action> [flags]

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

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

全域旗標

旗標	說明
`--profile`	此次呼叫要使用的具名設定檔（等同於設定 `ANTHROPIC_PROFILE`）。請參閱在工作區之間切換。
`--format`	輸出格式：`auto`、`json`、`jsonl`、`yaml`、`pretty`、`raw`、`explore`
`--transform`	使用 GJSON 路徑篩選或重塑回應
`-r`、`--raw-output`	列印字串結果時不加上外圍引號，類似 `jq -r`
`--base-url`	覆寫 API 基礎 URL
`--debug`	將完整的 HTTP 請求與回應列印至 stderr
`--format-error`、`--transform-error`	與 `--format` 和 `--transform` 相同，但套用於錯誤回應

輸出格式

ant models retrieve --model-id claude-opus-4-8 --format yaml

Output

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00:00:00Z"
...

互動式瀏覽器

ant models list --format explore

使用 GJSON 轉換輸出

使用 --transform 在列印前重塑回應。該運算式是一個 GJSON 路徑。對於列出端點，轉換會針對每個項目個別執行，而非針對外層封裝：

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

Output

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

擷取純量值

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-sonnet-4-6}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

Output

agent_011CYm1BLqPXpQRk5khsSXrs

傳遞請求主體

旗標

純量欄位直接對應至旗標。結構化欄位接受寬鬆的類 YAML 語法（不加引號的鍵、字串可選擇性加引號）或嚴格的 JSON：

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

可重複的旗標會建立陣列。每個 --tool 或 --event 會附加一個元素：

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

Stdin

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

Heredoc 的運作方式相同，且便於處理多行 YAML。將分隔符號加上引號（如 <<'YAML'）可停用主體內的變數展開。

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

檔案參照

接受檔案路徑的旗標（例如上傳命令的 --file）可接受純路徑：

ant beta:files upload --file ./report.pdf

若要將檔案內容內嵌至字串值欄位，請在路徑前加上 @：

ant beta:agents create \
  --name "Researcher" --model '{id: claude-sonnet-4-6}' \
  --system @./prompts/researcher.txt

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

ant messages create \
  --model claude-opus-4-8 \
  --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.0.text' --raw-output

除錯

在任何命令中加入 --debug，即可將確切的 HTTP 請求與回應（標頭與主體）列印至 stderr。API 金鑰會被遮蔽。

ant --debug beta:agents list

Output

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 參考文件中。若要在本機列出，請執行 ant --help，並在任何子命令後附加 --help 以查看其旗標與參數。

Was this page helpful?