CLIの使用

このページでは、すべてのエンドポイントに共通して適用される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...

グローバルフラグ

出力形式

autoはJSONを整形して出力し、リソースを作成または変更するコマンドのデフォルトです。リストおよび取得コマンドは、ターミナルに出力する場合はインタラクティブエクスプローラーがデフォルトとなり、パイプされる場合は整形されたJSONがデフォルトとなります。いずれのデフォルトも--formatで上書きできます。

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

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

リストエンドポイントは自動的にページネーションされます。デフォルトの形式では各項目が個別に書き出されます（jsonlモードでは1行につき1つのコンパクトな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

{"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の引用符なしで出力され、そのままシェル変数に代入できます。

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

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

リクエストボディの渡し方

適切な入力方法はデータの形状によって異なります。スカラーフィールドや短い構造化された値にはフラグを使用し、ネストされたボディや複数行のボディには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は1つの要素を追加します。

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"

ヒアドキュメントも同様に機能し、複数行の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

構造化されたフラグ値の内部では、パスを引用符で囲みます。Messages APIにPDFを送信するには次のようにします。

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://を、base64には@data://を使用します。リテラルの先頭の@はバックスラッシュでエスケープします（\@username）。

デバッグ

任意のコマンドに--debugを追加すると、正確なHTTPリクエストとレスポンス（ヘッダーとボディ）がstderrに出力されます。APIキーはマスクされます。

ant --debug beta:agents list

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を追加すると、そのフラグとパラメータが表示されます。