ant CLIの使い方 — コマンド構造とGJSONでの出力変換

コマンド構造を押さえる — resource actionパターン

ant CLIのコマンドはすべてant <resource> <action> [flags]という共通パターンに従います。ant CLIのインストール方法とant CLIの認証設定が済んでいる前提で、本記事はコマンドの組み立て方と入出力の扱いをまとめます。

このパターンさえ覚えてしまえば、新しいリソースが増えても学び直す量はわずかです。resourceとactionの組み合わせを変えるだけで、モデル一覧の取得もエージェントセッションの作成も同じ文法で書けます。違うのは各リソースが受け付けるフラグの中身だけです。

ネストしたリソースはコロンでつなぎ、階層をそのままコマンド名に反映させます。

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

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

エージェント・セッション・環境のようなベータ版のリソースはbeta:プレフィックス配下にあります。この名前空間のコマンドは、そのリソースに必要なanthropic-betaヘッダーを自動で付けるため、自分でヘッダーを指定する必要はありません。--beta <header>は既定のスキーマバージョンを上書きしたいときだけ使います。

ant beta:agents list --beta agents-2026-06-01

普段は指定しなくてよいフラグですが、新しいベータヘッダーが出た直後に旧バージョンの挙動で検証したい、といった過渡期には有効です。CLI自体のバージョンを上げる前に、まずヘッダーだけ切り替えて挙動を確かめられます。

主なグローバルフラグは次の通りです。

どのリソースが使えるか、各リソースがどんなフラグを受け付けるかを調べる方法は、記事の最後にまとめています。

出力フォーマットを切り替える

autoはJSONを整形して表示し、リソースを作成・変更するコマンドの既定値です。一覧系・取得系のコマンドは、端末に直接出力するときはインタラクティブなエクスプローラーを開き、パイプにつないだときは整形済みJSONにフォールバックします。--formatでどちらの既定も上書きできます。

ant models retrieve --model-id claude-opus-5 --format yaml

type: model
id: claude-opus-5
display_name: Claude Opus 5
created_at: "2026-07-24T00:00:00Z"

一覧エンドポイントは自動でページネーションを処理します。既定のフォーマットでは各項目が個別に書き出されるため(jsonlは1行1JSON、yamlはYAMLドキュメントの連続)、head・grep・--transformにそのままストリームできます。

インタラクティブなエクスプローラーは、大きなレスポンスを畳んで検索できるTUIです。矢印キーでノードを開閉し、/で検索、qで終了します。端末に接続されているときの一覧・取得コマンドは既定でこれを開き、--format exploreで明示的に開くこともできます。ネストの深いレスポンスをスクロールで追うより、必要なフィールドまで畳んで辿るほうが速いことが多く、手作業での調査には向いています。スクリプトに組み込む段階になったら、エクスプローラーではなく--format jsonlや--transformのような機械可読な形式に切り替えます。

GJSONで出力を変換する

--transformはレスポンスをGJSONパスで整形してから表示します。一覧エンドポイントでは、変換は封筒(レスポンス全体)ではなく各項目に対して個別に実行されます。

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

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

新しく作ったリソースのIDのような単一フィールドを取り出してシェル変数に代入したい場合は、--transformと--raw-outputを組み合わせます。JSONの引用符が付かない文字列として出力されます。

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-opus-5}' \
  --transform id --raw-output)
 
printf '%s\n' "$AGENT_ID"

--raw-outputと--format rawは別物です。--raw-outputは文字列結果からJSONの引用符を外すだけ(jq -r相当)、--format rawはレスポンス本文の生JSONバイトを自動ページネーションなしで出力し、一覧エンドポイントでは各項目ではなくページネーション用の封筒に--transformを適用します。

リクエストボディの渡し方 — フラグ・stdin・ファイル参照

渡すデータの形によって、使う入力手段が変わります。

スカラーフィールドは直接フラグに対応します。構造化フィールドは、クォート省略可の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-5}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

JSONやYAMLのドキュメントをstdinにパイプすれば、リクエストボディ全体を渡せます。stdinの値とフラグの値はマージされ、フラグが優先されます。

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

複数行のYAMLにはヒアドキュメントが便利です。区切り記号を<<'YAML'のようにクォートすると、本文内の変数展開を止められます。

ファイルパスを取るフラグ(アップロードコマンドの--file等)には、パスをそのまま渡します。

ant files upload --file ./report.pdf

ファイルの中身を文字列フィールドにインライン展開したいときは、パスの先頭に@を付けます。

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

構造化フラグ値の内側でファイル参照を使うときはパスをクォートで囲みます。バイナリファイルはCLIがファイル種別を検出して自動的にbase64エンコードします。特定のエンコードを強制したい場合は@file://(プレーンテキスト)か@data://(base64)を使い、先頭に文字通りの@を送りたいときはバックスラッシュでエスケープ(\@username)します。

@参照はネストした構造の中でも使えます。スキャンしたPDFをMessages APIに送り、抽出したテキストだけを--transformで取り出す例です。

ant messages create \
  --model claude-opus-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

content.#(type=="text").textは、レスポンスのcontent配列からtypeがtextである要素だけを選んでtextフィールドを取り出すGJSONの絞り込み構文です。配列の中から条件に合う要素だけを選びたいときは、この#(条件)という書き方を使います。

デバッグに--debugを使う

どのコマンドにも--debugを付けると、実際に送受信されたHTTPリクエストとレスポンス(ヘッダーとボディ)が標準エラー出力に表示されます。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>

エラーレスポンス自体を--transform・--formatで整形したい場合は、--transform-errorと--format-errorという対になったフラグを使います。ステータスコード別の対処やリトライ設計そのものはClaude APIのエラーハンドリング設計で扱っている領域なので、そちらもあわせて読むと切り分けがしやすくなります。

使えるリソースの一覧を調べる

ant CLIが公開しているAPIリソースは、Claude APIのエンドポイントとほぼ1対1で対応しています。エンドポイントごとのパラメータやレスポンス形式まで確認したいときはAPIリファレンスを見ますが、手元でざっと調べたいだけならant --helpで足ります。

ant --help
ant messages --help

トップレベルの--helpでリソースの一覧が、サブコマンドに付けた--helpでそのリソースが受け付けるフラグとパラメータが表示されます。新しいバージョンでリソースが追加・変更されても、この2つのコマンドで最新の対応状況を確認できます。ドキュメントを開かなくても、手元のバージョンが何に対応しているかをその場で確認できるのが、CLIならではの利点です。エンドポイントのリクエスト・レスポンスの詳細なスキーマまで追いたいときだけ、APIリファレンスに切り替えれば十分です。

つまずきやすいポイント

• --raw-outputと--format rawを混同する。前者は文字列の引用符を外すだけ、後者はページネーション処理をスキップした生バイトを返す
• 一覧コマンドの出力先で挙動が変わることを忘れる。端末に直接実行するとエクスプローラーが開き、パイプにつなぐとJSONに切り替わるため、スクリプト内で試したときと手打ちしたときで見た目が違って戸惑いやすい
• stdinとフラグを両方渡したときの優先順位を確認せずに使う。フラグの値がstdinの値を上書きするため、両方に同じフィールドを書くと意図と違う方が採用されることがある
• --transformが一覧では各項目に個別適用されることを忘れ、封筒全体を前提にしたGJSONパスを書いてしまう。一覧系と取得系でパスの起点が違う点は覚えておく必要がある
• beta:プレフィックスを付け忘れる。ベータ版のリソースは名前空間ごとコマンドが変わるため、プレフィックスを落とすとそのリソース自体が見つからないというエラーになる。エージェント・セッション・環境のように名前が似た一般的な単語ほど、うっかりプレフィックスなしで打ちがちな箇所でもある

いずれも、動かしてみて初めて気づく類の差です。パイプにつないだ状態で一度動作を確認してから、本番のスクリプトに組み込むと事故を防ぎやすくなります。

まとめ

ant CLIはresource actionという一貫した構造の上に、出力フォーマットの切り替え・GJSONによる変換・3通りのリクエストボディ入力を積み重ねた設計です。フラグの並びは覚えることが多く見えても、この骨格さえ押さえておけばant --helpとサブコマンドの--helpで残りを都度確認でき、暗記の負担は最小限に抑えられます。インストールや認証がまだの場合は、本文冒頭で紹介した記事から始めると、この記事のコマンド例がそのまま動きます。