Utilizzo della CLI

Questa pagina descrive i meccanismi di input e output della CLI ant che si applicano a ogni endpoint. Per installare ed eseguire l'autenticazione, consulta la Guida rapida. 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 visualizzarne i flag.

Le risorse in beta (inclusi agents, sessions, deployments ed environments) 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 aderire a una versione diversa dello schema).

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

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-5 --format yaml

type: model
id: claude-opus-5-5
display_name: Claude Opus 5.5
created_at: "2026-09-22T00:00:00Z"
...

Gli endpoint di elenco gestiscono automaticamente la paginazione. 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 consente di inviarli in modo pulito a head, grep e ai filtri --transform.

Esploratore interattivo

L'esploratore è una TUI con espansione e ricerca per navigare risposte di grandi dimensioni. I tasti freccia espandono e comprimono i nodi, / avvia la ricerca, 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 di stamparle. L'espressione è un percorso GJSON. Per gli endpoint di elenco la trasformazione viene eseguita su ogni singolo elemento, non sull'involucro:

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

Estrarre un valore scalare

Per acquisire un singolo campo come stringa senza virgolette (ad esempio, l'ID di una risorsa appena creata), combina --transform con --raw-output. Il risultato viene stampato senza 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-5}' \
  --transform id --raw-output)

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 corpi annidati o su più righe, 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 facoltative 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-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 l'intero corpo della richiesta. I campi provenienti da stdin vengono uniti ai flag, e i flag hanno la precedenza. Qui version è il token di locking ottimistico restituito da un precedente retrieve, e $AGENT_ID è stato acquisito come in Estrarre un valore 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 su più righe. Racchiudi 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-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 caricamento, accettano un percorso semplice:

ant files upload --file ./report.pdf

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

ant beta:agents create \
  --name "Researcher" --model '{id: claude-opus-5-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-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."}
  ]}'

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 un @ iniziale letterale con una barra rovesciata (\@username).

Debug

Aggiungi --debug a qualsiasi comando per stampare su stderr l'esatta richiesta e risposta HTTP (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: 2026-10-21
Authorization: Bearer <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 visualizzarne flag e parametri.

Passaggi successivi