0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@NaokiIshimura(Naoki Ishimura)

Claude API の公式CLI「ant」入門 ― インストールから ant apply による Infrastructure as Code まで 🐜

0
Posted at

はじめに 📝

Claude の公式ブログ記事「Building effective agent automations」を読んでいると、ant apply deployment.md のようなコマンドがさらっと登場します。この ant は、Anthropic 公式の Claude API 用コマンドラインツール です（リポジトリ: anthropics/anthropic-cli）。

この記事では、公式ドキュメントをもとに ant の基本的な使い方と、エージェントやデプロイメントをファイルで管理できる ant apply について解説します。

まずはどんなものか、サンプルを見てみましょう 👇

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

# エージェント定義ファイルから API リソースを作成・更新する
ant apply agents/summarizer.md
agents/summarizer.md
---
name: Summarizer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful assistant that writes concise summaries.

3行まとめ ✨

  • 🐜 ant は Claude API のすべてのリソースをサブコマンドとして扱える公式CLI。curl + jq の手書きJSONから解放される
  • 🔄 --transform（GJSON）・--format・@path によるファイル埋め込みなど、スクリプトで使いやすい機能が揃っている
  • 📦 ant apply を使うと、エージェント・環境・メモリストア・デプロイメント・Vault などを ファイルで宣言して API と同期 できる（Terraform 的な使い方）

ant とは 🤔

ant CLI は、ターミナルから Claude API にアクセスするためのツールです。すべての API リソースがサブコマンドとして公開されており、出力の整形、レスポンスのフィルタリング、YAML / JSON ファイルからの入力に対応しています。

curl と比べたときのメリットは次の通りです。

観点 curl ant
リクエストボディ JSON を手書き 型付きフラグ or YAML をパイプ
ファイルの埋め込み 自前でエンコード @path で文字列フィールドに埋め込み（バイナリは自動で base64）
レスポンスの抽出 jq が別途必要 --transform で GJSON クエリを内蔵
一覧APIのページング 自前でループ 自動でページング

インストールと認証 🔧

インストール

# macOS (Homebrew)
brew install anthropics/tap/ant

# Linux / WSL（リリースバイナリを直接取得）
VERSION=1.40.0
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.25 以上）
go install github.com/anthropics/anthropic-cli/cmd/ant@latest
export PATH="$PATH:$(go env GOPATH)/bin"

インストールできたか確認します。

ant --version

認証

ant auth login

ブラウザで Claude Console の OAuth フローが開き、認証情報がローカルに保存されます。API キーを作成・管理しなくても API を呼べるのが嬉しいポイントです。API キーの環境変数、ヘッドレス環境、複数ワークスペース、名前付きプロファイル、Workload Identity Federation などにも対応しています。

シェル補完

# zsh
ant @completion zsh > "${fpath[1]}/_ant"

# bash
ant @completion bash > /etc/bash_completion.d/ant

# fish
ant @completion fish > ~/.config/fish/completions/ant.fish

基本的な使い方 🚀

コマンド構造

コマンドは リソース アクション の形式です。ネストしたリソースはコロンでつなぎます。

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 ヘッダーは自動で付与されるので、自分で指定する必要はありません。

出力フォーマット --format

auto / json / jsonl / yaml / pretty / raw / explore から選べます。

ant models retrieve --model-id claude-opus-5-5 --format yaml
  • 作成・更新系コマンドのデフォルトは auto（JSON を整形表示）
  • 一覧・取得系コマンドは、ターミナルではインタラクティブエクスプローラー、パイプ時は整形 JSON がデフォルト
  • エクスプローラーは矢印キーで展開/折りたたみ、/ で検索、q で終了
ant models list --format explore

--transform で GJSON による抽出 🔍

--transform には GJSON パス を指定します。一覧系ではエンベロープではなく各要素に対して適用される点がポイントです。

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

作成したリソースの ID をシェル変数に入れたいときは、--raw-output（-r）と組み合わせます。jq -r と同じく、文字列をクォートなしで出力します。

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

printf '%s\n' "$AGENT_ID"

⚠️ --raw-output と --format raw は別物です。--format raw はレスポンスの生の JSON をそのまま出力し、自動ページングも行いません。

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

データの形に応じて3つの方法を使い分けます。

① フラグ：スカラー値や短い構造化データ向け。構造化フィールドは YAML 風のゆるい記法でも厳密な JSON でも書けます。

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

--tool のように繰り返し指定できるフラグは配列になります。

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

② 標準入力：ネストが深い・複数行のボディ向け。フラグと併用した場合はフラグが優先されます。

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

③ @ によるファイル参照：ファイルの内容を文字列フィールドに埋め込みます。

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

PDF のようなバイナリも、ファイル種別を判定して自動で base64 エンコードしてくれます。

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

エンコードを明示したい場合は @file://（プレーンテキスト）/ @data://（base64）を使います。先頭の @ を文字として送りたいときは \@username のようにエスケープします。

デバッグ 🐛

--debug を付けると、実際の HTTP リクエスト/レスポンスが stderr に出力されます（API キーはマスクされます）。

ant --debug beta:agents list

ant apply：リソースをコードで管理する 📦

ここからが冒頭のブログ記事で使われていた機能です。ant apply（CLI 1.30.0 以上が必要）は、エージェント・環境・スキル・メモリストア・デプロイメント・Vault をファイルから作成・更新します。リソース定義をリポジトリに置き、コードと同じレビューフローで変更できるようになります。

最初のエージェントを apply する

agents/ 配下に Markdown でエージェントを書いて apply します。フロントマターが設定、本文がシステムプロンプトになります。

ant apply agents/summarizer.md

ターミナルでは実行計画（plan）が表示され、承認を求められます。

± Name                    Plan
+ ./agents/summarizer.md  create

Resources  + 1 to create

Apply these changes? (y)es / (n)o / (d)etails y
  • d で新規リソースのフィールドや、更新時のフィールド単位の差分を確認できる
  • --dry-run で詳細な計画を表示するだけで終了する
  • ファイルを編集して再度 ant apply すると、計画が create ではなく update になる

claude-lock.json をコミットする 🔒

初回の ant apply は、実行したディレクトリに claude-lock.json（ロックファイル） を書き出します。各ファイルが作成したリソースの ID と、組織・ワークスペースの情報が記録されます。

claude-lock.json
{
  "version": 1,
  "origin": {
    "base_url": "https://api.anthropic.com",
    "organization_id": "1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f",
    "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  },
  "resources": {
    "./agents/summarizer.md": {
      "kind": "agent",
      "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "version": "1",
      "hash": "d23251c8d99b3613a64f3f8d87f5fad4",
      "remote_hash": "1b771bee5bdbf600a5ad972fdac32d94"
    }
  }
}

これをファイルと一緒にコミットしておくことで、次回の実行（手元でも CI でも）が同じリソースを更新するようになります。2つのハッシュで「ファイルが編集された」「ファイル外（Console など）でリソースが変更された」を検知します。リポジトリのルートで実行するのがおすすめです。

プロジェクトとして育てる 🌱

各リソースはディレクトリで種類を判別します。

リソース 置き場所・形式
エージェント agents/ の Markdown（本文が system）
環境 environments/ の YAML
メモリストア memory_stores/ の YAML
デプロイメント deployments/ の Markdown（本文が各セッションの開始メッセージ）
スキル SKILL.md を含むディレクトリ（慣例で skills/ 配下）
Vault vaults/ の YAML（display_name と metadata のみ。CLI 1.34.0 以上）

ポイントは リソース同士を相対パスで参照できることです。API が ID を期待する場所にファイルパスを書くと、ant apply が依存関係の順に作成して実際の ID を埋めてくれます。

deployments/nightly.md
---
name: Nightly review
agent: ../agents/reviewer.md # the API's agent field: sent as {type: agent, id, version}
environment_id: ../environments/cloud.yaml # sent as the environment's ID
resources:
  - path: ../memory_stores/review-notes.yaml
    access: read_write
schedule:
  type: cron
  expression: "0 3 * * *"
  timezone: America/Los_Angeles
---

Review any open pull requests. Start with the oldest.

ディレクトリごとまとめて apply できます。

ant apply .

種類の判定は、①ファイル内のトップレベル type フィールド → ②直上のディレクトリ名 → ③ファイル名の先頭（例: environment_staging.md）の順に行われます。どれにも当てはまらない README や CI 設定などはスキップされます（Vault だけはファイル名からは判定されないので、vaults/ に置くか type: vault を付けます）。

編集・削除時の挙動 ✏️

  • 引数なしの ant apply はロックファイルが追跡しているファイルをすべて同期
  • ファイルからフィールドを消すと、API がクリア可能なフィールドならリソース側でもクリアされる
  • Console などファイル外で変更されたリソースがあると refusing to apply で停止 → --force で上書き
  • ファイルを削除してもリソースは残る（警告のみ）→ --prune でアーカイブ/削除
  • Console や ant beta:agents create で作ったリソースは取り込めない（同じ内容のファイルを apply すると2つ目が作られる）。ただし Console の Export as code でダウンロードしたものは claude-lock.json 付きなので更新できる

CI で使う 🤖

ターミナルがない環境では確認プロンプトを出せないため、フラグが必要です。

  • マージ後のデフォルトブランチで ant apply --yes .（ディレクトリを明示しないと新規ファイルがスキップされる）
  • プルリクエストでは ant apply --dry-run . で計画をレビュアーに表示
  • 途中で失敗しても claude-lock.json はジョブの最後にコミットする（部分的な apply でも作成済みのものは記録されるため）
  • ロックファイルにロック機構はないので、apply は同時に1つだけ実行する
  • 認証は保存済み API キーより Workload Identity Federation を推奨
フラグ 効果
--dry-run 計画を表示して終了（ロックファイルも書かない）
--yes 確認なしで適用（ターミナルなしでは必須）
--force ファイル外で変更されたリソースも上書き
--prune ファイルから消えたリソースを削除
--upgrade GitHub URL で参照しているスキルを再解決
--lock-file <path> 使用するロックファイルを指定
--verbose, -v 変更のないリソースや全フィールドも表示

ブログ記事での使われ方 🗞️

冒頭の「Building effective agent automations」では、デイリーブリーフエージェントを次のように構築・運用していました。

ant apply vault.yaml                              # 認証情報を入れる Vault を作成
ant apply deployment.md                           # スケジュール実行の定義を作成・更新
ant beta:deployments run --deployment-id <id>     # 手動でテスト実行

agent.md / deployment.md / environment.yaml / memory_store_*.yaml / vault.yaml をリポジトリで管理し、claude-lock.json でリソース ID を追跡する、まさに ant apply の典型的な構成になっています。

まとめ 🎯

  • ant は Claude API の公式CLIで、curl + jq よりも短く安全に API を叩ける
  • --format / --transform / --raw-output / @path を覚えるとシェルスクリプトとの相性が抜群
  • ant apply でエージェントやデプロイメントをコードとしてレビュー・バージョン管理でき、CI からの自動反映も可能

まずは brew install anthropics/tap/ant → ant auth login → ant models list で触ってみて、次に手元のエージェントを agents/ に Markdown で書いて ant apply --dry-run . してみるのがおすすめです 🚀

参考リンク 🔗

0
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?