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

ant CLIとは — Anthropicが提供するClaude API用のコマンドラインツール

ant CLIは、AnthropicのClaude APIをターミナルから操作するコマンドラインツールです。APIのリソースがそれぞれサブコマンドになっています。

curlと比べると、型付きフラグやパイプしたYAMLでリクエストボディを組み立てられます。@pathでファイルの中身を文字列フィールドに展開でき、--transformでjqなしにレスポンスを絞り込めます。一覧エンドポイントのページネーションも自動です。

コマンド構造を押さえる — 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-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 agents listではなくant beta:agents listと打ちます。

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

どのリソースが使えるか、各リソースがどんなフラグを受け付けるかを調べる方法は、後半の「使えるリソースの一覧を調べる」で説明します。

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

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

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

type: model
id: claude-opus-5-5
display_name: Claude Opus 5.5
created_at: "2026-09-22T00: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-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5-5"}

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

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

名前の似た2つのオプションは、効く範囲がまったく違います。

リクエストボディの渡し方 — フラグ・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-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"

この例のversionは、先にretrieveで受け取った楽観的ロック用のトークンです。更新時にその値を添えて、他から先に更新されていないかをサーバー側に判定させます。

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

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等)には、パスをそのまま渡します。

ant files upload --file ./report.pdf

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

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

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

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

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."}
  ]}' \
  --transform 'content.#(type=="text").text' --raw-output

content.#(type=="text").textは、レスポンスのcontent配列からtypeがtextである最初の1要素を選び、そのtextフィールドを取り出すGJSONの絞り込み構文です。#(条件)は条件に合う最初の1要素を返し、すべて取り出すなら末尾に#を付けた#(条件)#と書きます。

送信内容を確かめたいときは--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>

ヘッダーのAnthropic-Betaを見れば、beta:名前空間のコマンドが実際にどのベータヘッダーを送ったかを確かめられます。

コマンドをつなげてスクリプトにする

一覧エンドポイントに--transform id --raw-outputを付けると、1行に1つの素のIDが出ます。headやxargsにそのまま渡せるので、先頭の1件を取って次のコマンドに引き渡す、といった連結が短く書けます。

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を使います。

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

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

エラーの種類ごとの対処やリトライ設計はClaude APIのエラーハンドリング設計にまとまっています。

セッションをシェルから動かす

エージェントと環境のIDが手元にあれば、セッションの作成から会話の読み出しまでをシェルだけで進められます。ant applyでリソースを管理している場合、IDはclaude-lock.jsonのresources配下の各エントリから読めます。

エージェントやセッションの操作をスクリプトに閉じ込めたい場合は、ant CLIのスクリプト化と自動化も参考になります。

curlのAPI呼び出しにCLIのログインを使う

ant auth loginで保存された認証情報は、curlなど別のHTTPクライアントにも流用できます。OAuthのアクセストークンはAuthorizationヘッダーにBearerトークンとして渡します。x-api-keyヘッダーは静的なAPIキー専用です。

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

ant auth print-credentials --access-tokenは、期限切れや期限間近のトークンを先に更新してから出力します。CLIのログインで作業するときは、ANTHROPIC_API_KEYとANTHROPIC_AUTH_TOKENを未設定にしておきます。どちらかが設定されているとantコマンドはそちらを優先し、意図しない組織やワークスペースに接続する原因になります。どの組織・ワークスペースでログインしているかはant auth statusで確かめられ、環境変数が上書きしているときは警告が出ます。認証まわりの詳細はant CLIの認証設定にあります。

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

公開されているAPIリソースの一覧は、APIリファレンスにあります。手元のバージョンで使えるものをその場で見たいときはant --helpで足ります。

ant --help
ant messages --help

トップレベルの--helpでリソースの一覧が、サブコマンドに付けた--helpでそのリソースが受け付けるフラグとパラメーターが表示されます。エンドポイントごとのリクエスト・レスポンスの詳細なスキーマまで追うときだけ、APIリファレンスに切り替えます。

Claude Codeからantを操作する

ant CLIがインストールされ認証も済んでいれば、Claude Codeに依頼するだけでAPIリソースを操作できます。Claude Codeがantをシェルから実行し、構造化された出力を読んで結果を判断するため、専用の連携コードは要りません。依頼文の例は次のとおりです。

• 直近のエージェントセッションを一覧して、エラーになったものを要約してほしい
• ./reportsのPDFをすべてFiles APIにアップロードして、発行されたIDを出力してほしい
• セッションsession_01...のイベントを取得して、エージェントがどこで詰まったかを教えてほしい

ワークスペースごとにプロファイルを分ける

ant auth loginで得られるトークンは、ログイン時に選んだ1つのワークスペースに結び付きます。複数のワークスペースで使うなら、ワークスペースごとに名前付きプロファイルでログインして切り替えます。

ant auth login --profile other-ws
ant profile activate other-ws

--profileはコマンドを1回実行する間だけ有効で、ant profile activateは以降のコマンドの既定を切り替えます。

組織の管理系APIを呼ぶ場合は、org:adminスコープを専用のプロファイルで取得します。

ant auth login --profile admin --scope "org:admin"
ant auth print-credentials --profile admin --access-token

org:adminを付与されるのは、組織の管理者・オーナー・プライマリオーナーのロールを持つメンバーだけです。発行されるトークンは組織全体に及ぶため、日常用のプロファイルとは分けておきます。

ant auth statusは、選ばれた認証情報の種類、有効なプロファイル、トークンが結び付いたワークスペースを表示します。状態を報告するコマンドで、疎通の死活確認ではありません。終了ステータスを条件にスクリプトを分岐させる使い方は避けます。

まとめ

スクリプトに組み込むなら、出力は--format jsonlと--transformで機械可読にし、実行前にant auth statusで送信先を確かめます。うまく動かないときは、--debugで送ったリクエストを見るところから始めます。