---
title: CLI | RunAPI
description: Installa e utilizza ogni comando CLI di RunAPI per azioni sui modelli,
  Task, File, Upload, informazioni sull'account, prezzi, Callback e Harness.
url: https://runapi.ai/it/docs/resources/cli.md
canonical: https://runapi.ai/it/docs/resources/cli
locale: it
---

> Versione HTML: https://runapi.ai/it/docs/resources/cli
> Indice del sito per gli agenti: https://runapi.ai/llms.txt

# CLI

La CLI RunAPI è un client terminale JSON-first per azioni sui modelli e
strumenti di gestione account. Scrive i dati dei risultati sullo standard output e
l'avanzamento operativo sullo standard error, quindi funziona altrettanto bene in un
terminale, negli script shell, nei job CI e in Harness.

## Installa

Installa la versione corrente su Linux o macOS:

```shell
curl -fsSL https://runapi.ai/cli/install.sh | sh
```

Sono disponibili anche le installazioni tramite Homebrew e dal sorgente Go:

```shell
brew install runapi-ai/tap/runapi
go install github.com/runapi-ai/cli/cmd/runapi@latest
```

Su Windows, scarica l'archivio `windows-amd64` o `windows-arm64` corrispondente dall'[ultima versione CLI][1], estrai `runapi.exe` e aggiungilo al `PATH`.



[1]: https://github.com/runapi-ai/cli/releases/latest

Blocca l'installer a una versione o a una directory di installazione quando un
deployment richiede un binario riproducibile:

```shell
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --version v0.13.1
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --dir "$HOME/.local/bin"
```

Il programma di installazione accetta anche `RUNAPI_VERSION`, `RUNAPI_INSTALL_DIR`,
`RUNAPI_INSTALL_BASE`, `RUNAPI_DOWNLOAD_BASE` e
`RUNAPI_SKIP_LIBC_CHECK=1`.

## Avvio rapido

Su una workstation, accedi nel browser e conferma la sorgente delle credenziali:

```shell
runapi login
runapi auth status
```

Esegui un'azione su un modello con un input JSON inline o un file JSON:

```shell
runapi nano-banana text-to-image --input '{"prompt":"a hummingbird drinking espresso","aspect_ratio":"1:1"}'
runapi nano-banana text-to-image --input-file request.json
```

La maggior parte delle azioni del modello sono asincrone. Attendono un risultato terminale per impostazione predefinita; aggiungi `--async` per restituire il Task immediatamente e usa `wait` in seguito:

```shell
TASK_ID=$(runapi suno text-to-music --async --input '{"model":"suno-v5","vocal_mode":"instrumental","style":"minimal piano","title":"Short Piano Theme"}' | jq -r '.id')
runapi wait "$TASK_ID" --service suno --action text-to-music
```

## Convenzioni dei comandi

Ogni comando emette JSON sullo standard output a meno che un'opzione non richieda esplicitamente
un valore scalare, come `files create --url-only` o `listen
--print-secret`. I messaggi di avanzamento e diagnostici rimangono sullo standard
error, così JSON può fluire in sicurezza verso `jq`:

```shell
runapi nano-banana text-to-image --input-file request.json \
  | jq -r '.images[].url' \
  | xargs -I{} curl -OL {}
```

Le azioni del modello accettano esattamente una sorgente di input per richiesta:

* `--input '<json object>'` fornisce JSON inline.
* `--input-file path/to/request.json` carica il JSON da un file.
* `--input-file -` legge il JSON dallo standard input.

Usa `runapi <service> <action> --help` prima di costruire una richiesta.
La CLI installata elenca i campi correnti dell'azione, gli identificatori di modello
accettati e i vincoli di validazione.

Queste opzioni globali si applicano a ogni comando:

| Opzione | Scopo |
|----------
| `--api-key` | Usa una chiave API per questa chiamata. Sostituisce `RUNAPI_API_KEY`. |
| `--base-url` | Usa un'origine API diversa per questa chiamata. |
| `--timeout` | Imposta il timeout globale del comando e l'attesa massima del Task. Il valore predefinito è 15 minuti. |
| `--poll-interval` | Imposta l'intervallo per il polling del Task. Il valore predefinito è 3 secondi. |
| `--async` | Ritorna immediatamente dopo aver inviato un'azione del modello asincrona. |
| `--quiet` | Sopprime il progresso sull'errore standard senza modificare l'output JSON. |

## Azioni del modello

La forma del comando del modello è `runapi <service> <action>`. Le azioni
sincrone restituiscono la risposta immediatamente. Per le azioni asincrone, il
comportamento predefinito è inviare, eseguire il polling e restituire il risultato terminale dell'attività;
`--async` restituisce invece la risposta di creazione.

Per i campi URL multimediali di primo livello, un percorso di file locale leggibile viene caricato
prima dell'esecuzione dell'azione del modello. Gli URL `http://` e `https://` esistenti vengono
inviati invariati. Utilizza `files create` quando hai bisogno di un URL temporaneo riutilizzabile,
quando la sorgente è un URL remoto, o quando la sorgente è dati Base64.

### Azioni audio e musicali

* `suno`: `add-instrumental`, `add-vocals`, `blend-lyrics`,
  `boost-style`, `check-voice`, `convert-audio`, `cover-audio`,
  `create-mashup`, `extend-music`, `generate-artwork`,
  `generate-lyrics`, `generate-midi`, `generate-persona`,
  `generate-voice`, `get-timestamped-lyrics`,
  `regenerate-validation-phrase`, `replace-section`,
  `separate-audio-stems`, `text-to-music`, `text-to-sound`,
  `visualize-music`, `voice-to-validation-phrase`
* `producer`: `text-to-music`
* `gemini-omni`: `create-audio`, `create-character`, `text-to-video`
* `openai-tts`: `text-to-speech`
* `fish-audio`: `text-to-speech`
* `gemini-tts`: `text-to-speech`
* `elevenlabs`: `isolate-audio`, `speech-to-text`, `text-to-dialogue`,
  `text-to-sound`, `text-to-speech`

### Azioni sulle immagini

* `nano-banana`: `edit-image`, `text-to-image`
* `imagen-4`: `remix-image`, `text-to-image`
* `seedream`: `decompose-layers`, `edit-image`, `text-to-image`
* `flux`: `remix-image`, `text-to-image`
* `flux-2`: `remix-image`, `text-to-image`
* `flux-kontext`: `text-to-image`
* `qwen-2`: `edit-image`, `text-to-image`
* `qwen-3`: `edit-image`, `text-to-image`
* `qwen-image`: `edit-image`, `remix-image`, `text-to-image`
* `recraft`: `remove-background`, `upscale-image`
* `z-image`: `text-to-image`
* `ideogram-v3`: `edit-image`, `reframe-image`, `remix-image`,
  `text-to-image`
* `gpt-image`: `edit-image`, `text-to-image`
* `gpt-image-2`: `edit-image`, `text-to-image`
* `gpt-4o-image`: `text-to-image`
* `midjourney`: `edit-image`, `get-seed`, `image-to-prompt`,
  `shorten-prompt`, `text-to-image`

### Azioni video e animazione

* `veo-3-1`: `extend-video`, `text-to-video`, `upscale-video`
* `seedance`: `text-to-video`
* `runway`: `extend-video`, `text-to-video`
* `runway-aleph`: `edit-video`
* `kling`: `avatar`, `edit-video`, `extend-video`, `image-to-video`,
  `motion-control`, `text-to-video`
* `infinitetalk`: `audio-to-video`
* `omnihuman`: `audio-to-video`, `human-identification`,
  `subject-detection`
* `wan`: `animate`, `edit-video`, `image-to-video`, `speech-to-video`,
  `text-to-image`, `text-to-video`
* `luma`: `modify-video`
* `hailuo`: `image-to-video`, `text-to-video`
* `volcengine-lip-sync`: `lip-sync-video`
* `happyhorse`: `edit-video`, `image-to-video`, `text-to-video`
* `grok-imagine`: `edit-image`, `extend`, `image-to-video`,
  `text-to-image`, `text-to-video`, `upscale-image`
* `topaz`: `upscale-image`, `upscale-video`
* `midjourney`: `extend-video`, `image-to-video`

L'elenco sopra è l'inventario completo delle azioni in questa versione della CLI.
Il contratto esatto di richiesta e risposta di ciascuna azione è disponibile nel
[Riferimento API](https://runapi.ai/it/docs/api/openai/chat-completions.md), e la guida del comando locale
è la fonte per i campi specifici della versione.

## Ciclo di vita dell'attività

Usa `get` per esaminare lo stato corrente di un Task asincrono senza
attendere. Usa `wait` per eseguire il polling finché non viene completato, fallisce o raggiunge il
timeout del comando. Entrambi i comandi richiedono il servizio e l'azione originali
affinché la CLI possa selezionare la forma corretta del risultato del Task.

```shell
runapi get "$TASK_ID" --service suno --action text-to-music
runapi wait "$TASK_ID" --service suno --action text-to-music --poll-interval 5s
```

## File

`runapi files create` mantiene il flusso temporaneo dell'URL di caricamento file. Carica un percorso locale, un URL remoto o una sorgente Base64 e restituisce un URL che scade dopo un'ora.

```shell
runapi files create ./reference.png --url-only
runapi files create --url https://example.test/reference.png --file-name reference.png
runapi files create --base64 "$(base64 < reference.png)" --file-name reference.png
```

Le scelte della sorgente si escludono a vicenda. `--url-only` stampa solo l'URL;
omettilo per ricevere la risposta JSON completa.

Usa il ciclo di vita dei File persistenti quando hai bisogno di un `file_id` stabile anziché di un URL:

```shell
runapi files create-file ./knowledge.pdf
runapi files list --order desc
runapi files retrieve file_123
runapi files content file_123 --output ./knowledge-copy.pdf
runapi files delete file_123
```

`content` richiede `--output`; passare `-` per scrivere i byte esatti del File sullo standard output. Consultare [Files and Uploads](https://runapi.ai/it/docs/resources/files.md) per i limiti, l'isolamento dell'account e il ciclo di vita REST.

## Caricamenti

Usa Uploads per inviare una o più Parts prima di comporre il File finale.
Create dichiara il conteggio finale dei byte e i metadati; ripeti `--part-id` in
ordine di composizione al momento del completamento:

```shell
runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream
runapi uploads add-part upload_123 ./archive.part-01
runapi uploads complete upload_123 --part-id part_123
runapi uploads cancel upload_123
```

## Account e prezzi

Ispeziona l'utente autenticato e l'Account selezionato, quindi interroga il saldo
e i contatori di spesa:

```shell
runapi account info
runapi account balance
```

`pricing list` legge i Listini Prezzi correnti. Filtra per servizio, azione o modello. `pricing quote` stima la prenotazione del Task per un servizio e un'azione richiesti; aggiungere `--model` quando l'azione è specifica per un modello e fornire gli Input di Pricing con `--params` o `--params-file`.

```shell
runapi pricing list --service suno --action text-to-music --model suno-v4
runapi pricing quote --service suno --action text-to-music --model suno-v4 \
  --params '{"vocal_mode":"auto_lyrics","prompt":"A chill lo-fi beat"}'
runapi pricing quote --service suno --action text-to-music --params-file pricing-inputs.json
```

I comandi di pricing non richiedono credenziali a meno che la quotazione non faccia riferimento
a un Task di origine di proprietà dell'Account.

## Autenticazione e configurazione

`runapi login` apre un flusso di autorizzazione nel browser e salva la credenziale risultante. Per i server e la CI, `auth import-token` accetta una Chiave API dallo standard input, la verifica per impostazione predefinita e la salva senza esporne il valore nell'elenco dei processi o nella cronologia della shell:

```shell
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status
runapi logout
```

`auth import-token --skip-verify` supporta la configurazione dell'immagine offline. Utilizzarlo solo quando la verifica non può essere eseguita durante la configurazione; `auth status` verifica la credenziale attiva in un secondo momento.

La precedenza della chiave API è `--api-key`, poi `RUNAPI_API_KEY`, poi il file
di configurazione CLI locale. La precedenza del Base URL è `--base-url`, poi
`RUNAPI_BASE_URL`, poi il Base URL salvato, poi `https://runapi.ai`.
Il file di configurazione è `~/.config/runapi/config.json`, oppure
`$XDG_CONFIG_HOME/runapi/config.json` quando `XDG_CONFIG_HOME` è impostato.

## Listener di callback locale

`runapi listen` riceve i Callback dei Task per una Chiave API selezionata e, facoltativamente, inoltra ogni callback firmato a un endpoint HTTP locale. L'accesso tramite browser è obbligatorio prima di utilizzare le operazioni di ascolto.

```shell
runapi login
runapi api-keys list --json
runapi listen http://localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
```

L'URL posizionale e `--forward-to` sono alternative. Il listener
scrive ogni corpo di callback firmato sullo standard output. Un'attività con
`callback_url` continua a consegnare a quell'URL e viene anche copiata nel
listener locale.

Dopo aver ricevuto un evento listener valido, la CLI lo conferma prima di
tentare la richiesta HTTP locale. Ogni evento viene inoltrato localmente una sola volta:
le risposte non-2xx e gli errori di connessione vengono segnalati nel terminale,
ma non fanno riprodurre l'evento al listener. Questo comportamento di debug locale non
modifica i tentativi di consegna per il `callback_url` di un Task.

Ogni Account può eseguire fino a 100 listener attivi per Chiave di Sottoscrizione Callback e 1.000 listener attivi in totale. Quando viene raggiunto un limite, ferma un listener inattivo oppure attendi e riprova. La risposta dell'API indica se la chiave selezionata, il tuo Account o la capacità complessiva del servizio è esaurita.

Un listener inattivo verifica la presenza di nuovi eventi circa ogni 15-30 secondi.
Gli eventi vengono normalmente trovati entro circa 15 secondi e vengono letti
immediatamente quando disponibili. Se viene raggiunto un limite, interrompi un listener
inattivo o attendi e riprova. Il comportamento di consegna e conferma esistente rimane invariato.

La selezione della chiave avviene nell'ordine: `--callback-api-key-id` per un singolo comando,
`callback_api_key_id` nel `.runapi.toml` del progetto, poi un selettore interattivo. La configurazione del progetto viene salvata alla radice Git, o
nella directory corrente fuori da un repository Git, e contiene solo l'ID stabile:

```toml
callback_api_key_id = "token_abc123"
```

Stampa il Listen Signing Secret di una chiave selezionata senza avviare un
listener, oppure ruotalo dopo un'esposizione:

```shell
runapi listen --print-secret --callback-api-key-id token_abc123
runapi listen --rotate-secret --callback-api-key-id token_abc123
```

La rotazione invalida i listener attivi per la chiave selezionata. Aggiorna
ogni verifier locale con il segreto appena generato prima di riavviare il
relativo listener.

## Harness

Installa la skill portabile della CLI RunAPI in un Harness supportato, ispeziona
i target supportati o rimuovi una skill installata:

```shell
runapi agent install-skill --target codex
runapi agent list-targets
runapi agent uninstall-skill --target codex
```

I target integrati sono `claude`, `codex`, `gemini`, `openclaw` e
`hermes`. `install-skill` accetta `--version` per bloccare una versione della skill,
`--target-dir` per una destinazione personalizzata, `--source` per un repository
sorgente e `--force` per sovrascrivere una directory di skill esistente.

## Completamento shell e versione

Genera script di completamento per Bash, Zsh, Fish o PowerShell. Ad
esempio, carica il completamento Bash nella shell corrente:

```shell
source <(runapi completion bash)
runapi completion zsh
runapi completion fish
runapi completion powershell
runapi version
```

Usa `runapi --help` per elencare i comandi, `runapi <command> --help` per le
opzioni di un comando e `runapi <service> <action> --help` per i campi di
un'azione del modello.

## Codici di uscita

I comandi terminano con un codice diverso da zero che gli script possono gestire:

| Codice | Significato |
|----------
| `0` | Successo |
| `2` | Errore di autenticazione o piattaforma non supportata |
| `3` | Crediti insufficienti o dipendenza locale richiesta mancante |
| `4` | Errore di validazione, non trovato o di analisi del manifest |
| `5` | Timeout, errore di download o mancata corrispondenza del checksum |
| `6` | Limite di frequenza raggiunto |
| `7` | Task fallito |

Per i campi di richiesta, i valori di stato del Task, i payload dei Callback, i corpi degli errori
e la gestione dei limiti di frequenza, prosegui con il [Riferimento
API](https://runapi.ai/it/docs/api/openai/chat-completions.md). Utilizza gli
[SDK](https://runapi.ai/it/docs/resources/sdks.md) quando lo stesso flusso di lavoro appartiene a un'applicazione.

---

## Altre risorse di RunAPI

- [Home](https://runapi.ai/it/.md)
- [Catalogo dei modelli](https://runapi.ai/it/models.md)
- [Prezzi](https://runapi.ai/it/pricing.md)
- [Fornitori](https://runapi.ai/it/models)
- [Documentazione](https://runapi.ai/it/docs/guides)
- [SDK](https://runapi.ai/it/sdk.md)
- [CLI](https://runapi.ai/it/cli.md)
- [MCP Server](https://runapi.ai/it/mcp.md)
- [Claude Code vs Cursor](https://runapi.ai/it/claude-code-vs-cursor.md)
- [Configurazione Cursor API](https://runapi.ai/it/cursor-api-setup.md)
- [RunAPI vs OpenRouter](https://runapi.ai/it/openrouter-alternative.md)
- [Enterprise](https://runapi.ai/it/contact.md)
- [Contatti](https://runapi.ai/it/contact.md)
- [Termini](https://runapi.ai/it/terms.md)
- [Privacy](https://runapi.ai/it/privacy.md)
- [Indice del sito per gli agenti](https://runapi.ai/llms.txt)

Contatti: contact@runapi.ai

## Dati strutturati

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "it",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/it",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/it/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "it",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/it",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/iticon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "it",
    "@type": "TechArticle",
    "headline": "CLI",
    "description": "Installa e utilizza ogni comando CLI di RunAPI per azioni sui modelli, Task, File, Upload, informazioni sull'account, prezzi, Callback e Harness.",
    "url": "https://runapi.ai/it/docs/resources/cli",
    "mainEntityOfPage": "https://runapi.ai/it/docs/resources/cli"
  }
]
```