ホーム / チュートリアル / ant CLI でClaude APIをターミナルから使う

ant CLI でClaude APIをターミナルから使う

Claude.ai エンジニアリング 8分で読めます

ant は Anthropic が提供する公式のコマンドラインツールで、Claude API のすべてのリソースをターミナルのサブコマンドとして扱えます。本記事は公式ドキュメントの内容を日本語で整理した非公式の解説です。

ant CLI とは何か

ant は、Claude API をターミナルから呼ぶためのツールです。API のリソースがそれぞれサブコマンドとして公開されていて、出力の整形、レスポンスの絞り込み、YAML や JSON ファイルからの入力に対応しています。

同じことは curl でもできますが、ant には次の違いがあります。

つまり ant は「curl の置き換え」というより、API を手元で触るとき・スクリプトから叩くときの定型作業を肩代わりするツールです。

インストールと認証

macOS では Homebrew が使えます。

brew install anthropics/tap/ant

Linux や WSL では、リリースのバイナリを直接取得します。

VERSION=1.22.1
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
  x86_64) ARCH=amd64 ;;
  aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

Go 1.22 以降があれば、ソースからも入ります。バイナリは $(go env GOPATH)/bin に置かれるので、必要なら PATH に追加してください。

go install github.com/anthropics/anthropic-cli/cmd/ant@latest

入ったかどうかは ant --version で確認できます。

認証は ant auth login です。ブラウザが開いて Claude Console に対する OAuth の流れが走り、得られた資格情報がローカルに保存されます。API キーを自分で作って管理しなくてよいのがこの方法の利点です。

ant auth login

環境変数の API キーを使う、ブラウザのないホストで認証する、複数のワークスペースを名前付きプロファイルで切り替える、Workload Identity Federation を使う、といった方法は公式の認証オプションのページにまとまっています。

ここまで済んだら、最初のリクエストを送れます。

ant messages create \
  --model claude-opus-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

返ってくるのは API のオブジェクトそのものです。標準出力が端末のときは読みやすく整形されます。

コマンドの構造

コマンドは リソース アクション の形に揃っています。入れ子になったリソースはコロンでつなぎます。

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...

ベータのリソース（agents、sessions、deployments、environments、skills など）は beta: の下にあります。この名前空間のコマンドはそのリソースに必要な anthropic-beta ヘッダーを自動で送るので、自分でヘッダーを指定する必要はありません。既定を上書きしたいとき（別のスキーマ版を選ぶときなど）だけ --beta <header> を使います。

リソースの一覧は ant --help、各サブコマンドのフラグはそのサブコマンドに --help を付けると出ます。

どのコマンドでも共通に使えるフラグは次のとおりです。

出力を整形する

既定の auto は JSON を読みやすく整形します。リソースを作成・更新するコマンドはこれが既定です。一覧と取得のコマンドは、端末に出力するときは対話的なエクスプローラが既定になり、パイプでつないだときは整形済み JSON になります。どちらも --format で上書きできます。

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

エクスプローラは大きなレスポンスを折りたたみながら見るための TUI です。矢印キーで開閉、/ で検索、q で終了します。明示的に開くときは --format explore を渡します。

一覧系のエンドポイントは自動でページングされます。既定の形式では項目ごとに書き出される（jsonl なら 1 行に 1 オブジェクト、yaml なら YAML ドキュメントの連続）ので、head や grep、--transform にそのまま流し込めます。

--transform は GJSON のパスでレスポンスを整形します。一覧系では封筒（envelope）ではなく各項目に対して適用される点が要点です。

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

1 つのフィールドだけを引用符なしで取り出したいときは、--transform と --raw-output を組み合わせます。新しく作ったリソースの ID をシェル変数に入れる、といった用途にそのまま使えます。

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

紛らわしいので区別しておきます。--raw-output は文字列の結果から JSON の引用符を外すだけです。--format raw はレスポンスの生の JSON バイト列を、自動ページングせずに出します。しかも一覧系では --transform が各項目ではなくページングの封筒に適用されます。別物として覚えてください。

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

渡し方は 3 通りあり、データの形で選びます。スカラー値や短い構造ならフラグ、入れ子や複数行なら標準入力、ファイルの中身を入れたいなら@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 回につき 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 のドキュメントを流すと、リクエストボディ全体をそこから与えられます。標準入力の内容とフラグは合成され、衝突したときはフラグが勝ちます。

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

ヒアドキュメントの区切り文字を <<'YAML' のように引用符で囲むと、本文の中で変数展開が起きません。誤って $ が展開されるのを防げます。

ファイルを扱うフラグ（アップロードコマンドの --file など）は、パスをそのまま受け取ります。一方、文字列のフィールドにファイルの中身を差し込みたいときは、パスの先頭に @ を付けます。

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

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

構造を持つフラグの値の中で使うときは、パスを引用符で囲みます。PDF を Messages API に送る例です。

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

ファイルの種類は自動で判別され、バイナリは base64 に符号化されます。明示したいときは @file://（プレーンテキスト）または @data://（base64）を使います。先頭の @ をそのまま文字として送りたい場合は、バックスラッシュで打ち消します（\@username）。

デバッグと次の一歩

どのコマンドにも --debug を足せます。実際に送られた HTTP リクエストと返ってきたレスポンスを、ヘッダーと本文まで標準エラーに出します。API キーは伏せ字になります。

ant --debug beta:agents list

出力には Anthropic-Beta や Anthropic-Version といったヘッダーがそのまま並ぶので、「ベータヘッダーが本当に付いているか」「どのバージョンで呼ばれているか」をコマンドの結果ではなく実測で確かめられます。仕様どおりに動かないときは、まずここを見るのが早道です。

シェル補完も同梱されています。bash / zsh / fish / PowerShell 用のスクリプトを生成できます。

ant @completion zsh > "${fpath[1]}/_ant"
ant @completion bash > /etc/bash_completion.d/ant
ant @completion fish > ~/.config/fish/completions/ant.fish

ここから先は、用途に応じて次の 3 つを見るとよいでしょう。認証の選択肢（API キー、ブラウザのないホスト、複数ワークスペース、名前付きプロファイル）、コマンドの詳細（構造・出力形式・GJSON・リクエストボディ）、そしてスクリプト化と自動化（API リソースのバージョン管理、Claude Code からの利用）です。エンドポイントごとのパラメータとレスポンスのスキーマは API リファレンスにあります。

本記事は Anthropic の公式ドキュメントに基づく非公式の日本語解説です。バージョン番号やフラグの仕様は変わることがあるため、実際に使う前に公式ドキュメントで最新の内容をご確認ください。

関連チュートリアル / 次に読む

Claude APIのエラーコードと対処 Claude呼び出し前にトークン数を数える Claude API の Files API でファイルを扱う Claude Managed Agents とは何か Claude APIのレート制限
← チュートリアル一覧へ戻る カテゴリで探す