Utilizzo della CLI

Questa pagina descrive le meccaniche di input e output della CLI ant che si applicano a tutti gli endpoint. Per l'installazione e l'autenticazione, consulta la Guida rapida. Per concatenare comandi e gestire le risorse con il controllo di versione, consulta Scripting e automazione della CLI.

Struttura dei comandi

I comandi seguono un pattern risorsa azione. 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, 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 aderire a una versione diversa dello schema).

ant models list
ant messages create --model claude-opus-4-8 --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'explorer interattivo quando scrivono su un terminale, e il JSON formattato quando l'output è in pipe. Sovrascrivi entrambi i valori predefiniti con --format:

ant models retrieve --model-id claude-opus-4-8 --format yaml

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00: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 si integra perfettamente in streaming con head, grep e i filtri --transform.

Explorer interattivo

L'explorer è una TUI con funzioni di espansione/compressione 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 connessi 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 path GJSON. Per gli endpoint di elenco la trasformazione viene eseguita su ogni elemento individualmente, non sull'envelope:

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

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-4-5"}

Estrarre uno scalare

Per catturare 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-sonnet-4-6}' \
  --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 campi scalari e valori strutturati brevi, invia in pipe un documento via stdin per corpi annidati o multi-riga, e usa i riferimenti @file per inserire il contenuto di 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) o 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-4-8}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

Invia in pipe un documento JSON o YAML a stdin per fornire l'intero corpo della richiesta. I campi da stdin vengono uniti ai flag, con i flag che hanno la precedenza. Qui version è il token di locking ottimistico 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 multi-riga. 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-4-8
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 inline il contenuto di un file in un campo di tipo stringa, anteponi @ al percorso:

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

All'interno di valori di flag strutturati, racchiudi il percorso tra virgolette. Per inviare un PDF all'API Messages:

ant messages create \
  --model claude-opus-4-8 \
  --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.0.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 un @ iniziale letterale con una barra rovesciata (\@username).

Debugging

Aggiungi --debug a qualsiasi comando per stampare la richiesta e la risposta HTTP esatte (header e corpo) su stderr. 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 visualizzarne i flag e i parametri.