Utilizzo della CLI

Questa pagina tratta i meccanismi di input e output della CLI ant che si applicano a ogni endpoint. Per installare e autenticarti, consulta il Quickstart. Per concatenare comandi e gestire le risorse con il controllo di versione, consulta Scripting e automazione della 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 devi passarlo tu stesso. 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 --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 list e retrieve usano per impostazione predefinita l'explorer interattivo quando scrivono su un terminale, e il JSON in formato leggibile quando l'output è 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 list effettuano 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 consente uno streaming pulito verso head, grep e i filtri --transform.

Explorer interattivo

L'explorer è una TUI con funzioni di compressione e ricerca per esplorare risposte di grandi dimensioni. I tasti freccia espandono e comprimono i nodi, / esegue una ricerca, q esce. I comandi list e retrieve 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 percorso GJSON. Per gli endpoint list 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"}
{"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 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 corpi annidati o multiriga, 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 l'intero corpo della richiesta. I campi provenienti 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 multiriga. 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
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 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-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 un @ iniziale letterale con una barra rovesciata (\@username).

Debug

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 visualizzarne flag e parametri.

Passaggi successivi