Menggunakan CLI

Halaman ini membahas mekanisme input dan output CLI ant yang berlaku di setiap endpoint. Untuk menginstal dan melakukan autentikasi, lihat Quickstart. Untuk merangkai perintah dan mengelola versi sumber daya, lihat Scripting dan otomatisasi CLI.

Struktur perintah

Perintah mengikuti pola resource action. Sumber daya bertingkat menggunakan tanda titik dua:

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

Jalankan ant --help untuk daftar sumber daya lengkap, atau tambahkan --help ke subperintah apa pun untuk melihat flag-nya.

Sumber daya dalam versi beta (termasuk agents, sessions, deployments, dan environments) berada di bawah prefiks beta:. Perintah dalam namespace ini secara otomatis mengirim header anthropic-beta yang sesuai untuk sumber daya tersebut, sehingga Anda tidak perlu menyertakannya sendiri. Gunakan --beta <header> hanya untuk menimpa nilai default (misalnya, untuk memilih versi skema yang berbeda).

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

Flag global

Format output

auto mencetak JSON dengan format rapi (pretty-print) dan merupakan default untuk perintah yang membuat atau memodifikasi sumber daya. Perintah list dan retrieve secara default menggunakan explorer interaktif saat menulis ke terminal, dan JSON berformat rapi saat di-pipe. Timpa salah satu default tersebut dengan --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"
...

Endpoint list melakukan paginasi otomatis. Dalam format default, setiap item ditulis secara terpisah (satu objek JSON ringkas per baris dalam mode jsonl, aliran dokumen YAML dalam mode yaml), yang mengalir dengan bersih ke head, grep, dan filter --transform.

Explorer interaktif

Explorer adalah TUI lipat-dan-cari untuk menelusuri respons berukuran besar. Tombol panah memperluas dan menciutkan node, / untuk mencari, q untuk keluar. Perintah list dan retrieve membukanya secara default saat terhubung ke terminal. Berikan --format explore untuk membukanya secara eksplisit:

ant models list --format explore

Mentransformasi output dengan GJSON

Gunakan --transform untuk membentuk ulang respons sebelum dicetak. Ekspresinya adalah path GJSON. Untuk endpoint list, transformasi dijalankan terhadap setiap item secara individual, bukan terhadap envelope-nya:

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": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5"}

Mengekstrak nilai skalar

Untuk mengambil satu field sebagai string tanpa tanda kutip (misalnya, ID sumber daya yang baru dibuat), pasangkan --transform dengan --raw-output. Hasilnya dicetak tanpa tanda kutip JSON dan siap ditetapkan ke variabel shell:

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

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

Mengirim body permintaan

Mekanisme input yang tepat bergantung pada bentuk datanya: gunakan flag untuk field skalar dan nilai terstruktur yang pendek, pipe dokumen stdin untuk body bertingkat atau multibaris, dan gunakan referensi @file untuk memasukkan isi file ke field string atau biner apa pun.

Flag

Field skalar dipetakan langsung ke flag. Field terstruktur menerima sintaks longgar mirip YAML (key tanpa tanda kutip, tanda kutip opsional di sekitar string) atau JSON ketat:

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

Flag yang dapat diulang membentuk array. Setiap --tool atau --event menambahkan satu elemen:

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

Stdin

Pipe dokumen JSON atau YAML ke stdin untuk menyediakan body permintaan lengkap. Field dari stdin digabungkan dengan flag, dengan flag yang diutamakan. Di sini version adalah token optimistic-locking yang dikembalikan oleh retrieve sebelumnya, dan $AGENT_ID diambil seperti pada Mengekstrak nilai skalar:

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

Heredoc bekerja dengan cara yang sama dan praktis untuk YAML multibaris. Beri tanda kutip pada delimiter (seperti pada <<'YAML') untuk menonaktifkan ekspansi variabel di dalam body.

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

Referensi file

Flag yang menerima path file, seperti --file pada perintah upload, menerima path biasa:

ant files upload --file ./report.pdf

Untuk menyisipkan isi file ke dalam field bernilai string, awali path dengan @:

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

Di dalam nilai flag terstruktur, bungkus path dengan tanda kutip. Untuk mengirim PDF ke 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

CLI mendeteksi tipe file dan mengodekan file biner sebagai base64 secara otomatis. Untuk memaksa pengodean tertentu, gunakan @file:// untuk teks biasa atau @data:// untuk base64. Escape karakter @ literal di awal dengan backslash (\@username).

Debugging

Tambahkan --debug ke perintah apa pun untuk mencetak permintaan dan respons HTTP yang sebenarnya (header dan body) ke stderr. Kunci API disamarkan.

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

Sumber daya yang tersedia

Setiap sumber daya API yang diekspos CLI didokumentasikan dalam referensi API. Untuk daftar lokal, jalankan ant --help, dan tambahkan --help ke subperintah apa pun untuk melihat flag dan parameternya.

Langkah selanjutnya