---
title: Utilizzo della CLI
url: https://platform.claude.com/docs/it/cli-sdks-libraries/cli/using
description: Struttura dei comandi, formati di output, trasformazioni GJSON, corpi delle richieste e debug per la CLI ant.
---

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](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/quickstart). Per concatenare comandi e gestire le risorse con il controllo di versione, consulta [Scripting e automazione della CLI](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/scripting).

## Struttura dei comandi

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

```text wrap
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).

```bash
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

| Flag                                  | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile`                           | Profilo con nome da usare per questa invocazione (equivalente a impostare `ANTHROPIC_PROFILE`). Consulta [Passare da un workspace all'altro](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/authentication#switch-between-workspaces).                                                                                                                                                                                                                                                    |
| `--format`                            | Formato di output: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore`                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--transform`                         | Filtra o rimodella la risposta con un [percorso GJSON](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/using#transform-output-with-gjson)                                                                                                                                                                                                                                                                                                                                                  |
| `-r`, `--raw-output`                  | Stampa i risultati di tipo stringa senza virgolette, come `jq -r`                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `--base-url`                          | Sovrascrive l'URL di base dell'API                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--workspace-id`                      | Opzionale. ID del workspace (`wrkspc_...`) da inviare come header `anthropic-workspace-id`, per le chiavi API con accesso a più workspace (equivalente a impostare `ANTHROPIC_WORKSPACE_ID`). Consulta [Selezionare un workspace](https://platform.claude.com/docs/it/manage-claude/authentication#select-a-workspace). I comandi dell'[Admin API](https://platform.claude.com/docs/it/manage-claude/admin-api) accettano un proprio `--workspace-id`, che indica invece il workspace che gestiscono. |
| `--debug`                             | Stampa la richiesta e la risposta HTTP complete su stderr                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--format-error`, `--transform-error` | Come `--format` e `--transform` ma applicati alle [risposte di errore](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/scripting#inspect-errors)                                                                                                                                                                                                                                                                                                                                           |

## 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](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/using#interactive-explorer) quando scrivono su un terminale, e il JSON in formato leggibile quando l'output è reindirizzato tramite pipe. Sovrascrivi entrambi i valori predefiniti con `--format`:

```bash
ant models retrieve --model-id claude-opus-5-5 --format yaml
```

```yaml Output
type: model
id: claude-opus-5-5
display_name: Claude Opus 5.5
created_at: "2026-09-22T00: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:

```bash
ant models list --format explore
```

## Trasformare l'output con GJSON

Usa `--transform` per rimodellare le risposte prima della stampa. L'espressione è un [percorso GJSON](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). Per gli endpoint list la trasformazione viene eseguita su ogni singolo elemento, non sull'involucro:

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

```jsonl Output
{"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 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:

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

printf '%s\n' "$AGENT_ID"
```

```text Output wrap
agent_011CYm1BLqPXpQRk5khsSXrs
```

<Note>
  `--raw-output` è distinto da `--format raw`. `--raw-output` rimuove le virgolette JSON dai risultati di tipo stringa, come `jq -r`. `--format raw` stampa i byte JSON grezzi del corpo della risposta senza paginazione automatica; sugli endpoint list applica `--transform` all'involucro di paginazione anziché a ogni elemento.
</Note>

## 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:

```bash
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:

```bash
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, 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](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/using#extract-a-scalar):

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

```bash
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 upload, accettano un percorso semplice:

```bash
ant files upload --file ./report.pdf
```

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

```bash
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:

```bash
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."}
  ]}' \
  --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.

```bash
ant --debug beta:agents list
```

```text Output wrap
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](https://platform.claude.com/docs/it/api/cli/messages/create). Per un elenco locale, esegui `ant --help`, e aggiungi `--help` a qualsiasi sottocomando per visualizzarne flag e parametri.

## Passaggi successivi

<CardGroup cols={3}>
  <Card title="Scripting e automazione della CLI" icon="code" href="https://platform.claude.com/docs/it/cli-sdks-libraries/cli/scripting">
    Controllo di versione delle risorse API, pattern di scripting e utilizzo da Claude Code
  </Card>

  <Card title="Riferimento API" icon="book" href="https://platform.claude.com/docs/it/api/cli/messages/create">
    Parametri specifici degli endpoint, campi delle richieste e schemi delle risposte
  </Card>

  <Card title="Opzioni di autenticazione della CLI" icon="lock" href="https://platform.claude.com/docs/it/cli-sdks-libraries/cli/authentication">
    Chiavi API, host headless, workspace multipli e profili con nome
  </Card>
</CardGroup>