Utilizzo della CLI

Questa pagina tratta i meccanismi di input e output della CLI ant che si applicano a ogni endpoint. Per l'installazione e l'autenticazione, consulta il Quickstart. Per concatenare comandi e gestire le risorse con il controllo di versione, consulta Scripting e automazione con la CLI.



Struttura dei comandi

I comandi seguono uno schema resource action. Le risorse annidate usano i due punti:

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

Esegui ant --help per l'elenco completo delle risorse, oppure aggiungi --help a qualsiasi sottocomando per vederne i flag.

Le risorse in beta (inclusi agents, sessions, deployments, environments e skills) si trovano sotto il prefisso beta:. I comandi in questo namespace inviano automaticamente l'header anthropic-beta appropriato per quella risorsa, quindi non è necessario passarlo manualmente. Usa --beta <header> solo per sovrascrivere il valore predefinito (ad esempio, per scegliere una versione diversa dello schema).

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 globali



Formati di output

auto stampa il JSON in formato leggibile ed è il valore predefinito per i comandi che creano o modificano risorse. I comandi di elenco e recupero usano per impostazione predefinita l'esploratore interattivo quando scrivono su un terminale, e il JSON formattato quando l'output viene reindirizzato tramite pipe. Sovrascrivi entrambi i valori predefiniti con --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"
...

Gli endpoint di elenco eseguono la paginazione automaticamente. Nei formati predefiniti ogni elemento viene scritto separatamente (un oggetto JSON compatto per riga in modalità jsonl, un flusso di documenti YAML in modalità yaml), il che si integra perfettamente in streaming con head, grep e i filtri --transform.



Esploratore interattivo

L'esploratore è una TUI con funzioni di espansione e ricerca per navigare risposte di grandi dimensioni. I tasti freccia espandono e comprimono i nodi, / cerca, q esce. I comandi di elenco e recupero lo aprono per impostazione predefinita quando sono collegati a un terminale. Passa --format explore per aprirlo esplicitamente:

ant models list --format explore



Trasformare l'output con GJSON

Usa --transform per rimodellare le risposte prima della stampa. L'espressione è un percorso GJSON. Per gli endpoint di elenco la trasformazione viene eseguita su ogni singolo elemento, non sull'envelope:

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



Estrarre uno scalare

Per catturare un singolo campo come stringa senza virgolette (ad esempio, l'ID di una risorsa appena creata), abbina --transform a --raw-output. Il risultato viene stampato senza le virgolette JSON ed è pronto per essere assegnato a una variabile di 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



Passare i corpi delle richieste

Il meccanismo di input corretto dipende dalla forma dei dati: usa i flag per i campi scalari e i valori strutturati brevi, invia tramite pipe un documento su stdin per i corpi annidati o multilinea, e usa i riferimenti @file per inserire il contenuto di un file in qualsiasi campo stringa o binario.



Flag

I campi scalari corrispondono direttamente ai flag. I campi strutturati accettano una sintassi rilassata simile a YAML (chiavi senza virgolette, virgolette opzionali attorno alle stringhe) oppure JSON rigoroso:

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

I flag ripetibili costruiscono array. Ogni --tool o --event aggiunge un elemento:

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

Invia tramite pipe un documento JSON o YAML su stdin per fornire il corpo completo della richiesta. I campi provenienti da stdin vengono uniti ai flag, con i flag che hanno la precedenza. Qui version è il token di optimistic locking restituito da un precedente retrieve, e $AGENT_ID è stato catturato come in Estrarre uno scalare:

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

Gli heredoc funzionano allo stesso modo e sono comodi per YAML multilinea. Metti il delimitatore tra virgolette (come in <<'YAML') per disabilitare l'espansione delle variabili all'interno del corpo.

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



Riferimenti a file

I flag che accettano un percorso di file, come --file nel comando di upload, accettano un percorso semplice:

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

Per inserire il contenuto di un file in un campo di tipo stringa, anteponi @ al percorso:

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

All'interno dei valori strutturati dei flag, racchiudi il percorso tra virgolette. Per inviare un PDF alla 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

La CLI rileva il tipo di file e codifica automaticamente i file binari in base64. Per forzare una codifica specifica usa @file:// per il testo semplice o @data:// per base64. Esegui l'escape di una @ letterale iniziale con una barra rovesciata (\@username).



Debugging

Aggiungi --debug a qualsiasi comando per stampare su stderr la richiesta e la risposta HTTP esatte (header e corpo). Le chiavi API vengono oscurate.

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



Risorse disponibili

Ogni risorsa API esposta dalla CLI è documentata nel riferimento API. Per un elenco locale, esegui ant --help, e aggiungi --help a qualsiasi sottocomando per vederne i flag e i parametri.



Prossimi passi