---
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 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](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 con la 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 è necessario passarlo manualmente. 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).                                                                                                                                                                                                                                                   |
| `--api-key-stdin`                     | Legge la chiave API dallo standard input. Il flag legge tutto lo standard input, quindi passa il corpo della richiesta tramite [flag](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/using#flags).                                                                                                                                                                                                                                                                                       |
| `--auth-token-stdin`                  | Legge il bearer token dallo standard input. Il flag legge tutto lo standard input, quindi passa il corpo della richiesta tramite [flag](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/using#flags).                                                                                                                                                                                                                                                                                     |
| `--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`                      | Facoltativo. ID del workspace (`wrkspc_...`) da inviare come header `anthropic-workspace-id`, per 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 di elenco e recupero usano per impostazione predefinita l'[esploratore interattivo](https://platform.claude.com/docs/it/cli-sdks-libraries/cli/using#interactive-explorer) quando scrivono su un terminale, e il JSON formattato quando l'output viene 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 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:

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

## Trasformare l'output con GJSON

Usa `--transform` per rimodellare le risposte prima di stamparle. L'espressione è un [percorso GJSON](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). Per gli endpoint di elenco 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 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:

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

<Note>
  `--raw-output` è diverso 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 di elenco 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 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:

```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, 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](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 su più righe. 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 caricamento, accettano un percorso semplice:

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

Per inserire il contenuto di un file in un campo con valore 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."}
  ]}'
```

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.

```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: 2026-10-21
Authorization: Bearer <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 con la CLI" icon="code" href="https://platform.claude.com/docs/it/cli-sdks-libraries/cli/scripting">
    Controllo di versione delle risorse API, schemi 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>