# Tripo CLI: lascia che l’IA trasformi testo e immagini in modelli 3D

Tripo CLI è progettata per gli agenti IA e rende la creazione 3D semplice come chattare. Che tu stia lavorando in uno strumento di coding IA come Codex, Claude Code o Cursor, o usando direttamente la CLI, bastano una descrizione in linguaggio naturale, un’immagine o un modello esistente per generare o trasformare modelli 3D, animazioni e altri asset. La CLI completa automaticamente l’intero flusso: non serve conoscere API, versioni dei modelli o parametri complessi.

## Devo usare la CLI o l’API?

Tripo è disponibile in due versioni: prenditi dieci secondi per scegliere quella giusta.

| Prodotto | Ideale per | Dove andare |
| --- | --- | --- |
| **Tripo CLI (questa pagina)** | Principianti: accedi rapidamente alle funzionalità di IA 3D tramite i più diffusi strumenti di vibe coding | Continua a leggere |
| **Tripo API** | Sviluppatori professionisti: integra le funzionalità di IA 3D in siti web, app o nei tuoi sistemi aziendali | [Guida rapida](/it/docs/quick-start) |

Non sei sicuro? Prova prima questa pagina: l’installazione è gratuita e i crediti si spendono solo quando generi davvero un modello.

## Installazione e accesso (scegli uno dei due percorsi)

Scegli uno dei due percorsi di installazione qui sotto.

### Percorso uno: fai installare tutto all’IA (consigliato)

Se usi già Cursor, Claude Code, Codex o un altro assistente IA in grado di eseguire comandi nel terminale, questo è il percorso più semplice. Copia il prompt qui sotto e invialo per intero al tuo assistente:

```text
Configura Tripo CLI per me e spiega ogni passaggio. Verifica che Node.js 20 o successivo sia installato, quindi esegui npm install -g tripo-cli. Chiedimi poi di completare tripo login nel browser; non chiedermi di incollare una chiave API nella chat. Infine, esegui tripo doctor e dimmi se i controlli di autenticazione, rete e saldo sono superati.
```

Ecco cosa succede:

1. L’IA controlla il tuo computer e, se Node.js manca, ti aiuta prima a installarlo;
2. L’IA esegue il comando di installazione;
3. Tocca a te: il browser apre la pagina di accesso di Tripo — accedi e approva il codice di verifica mostrato nel tuo terminale (questo passaggio spetta a te; non inviare mai nessuna chiave all’IA);
4. L’IA esegue `tripo doctor`; quando tutti i controlli sono superati, la configurazione è completa.

Poi passa direttamente alla sezione successiva, “Crea il tuo primo modello 3D”.

<details>
<summary><strong>Problemi?</strong> L’IA si è bloccata o ha incontrato un errore</summary>

- Incolla all’IA l’errore del terminale così com’è e lasciala continuare: può risolvere la maggior parte dei problemi;
- L’accesso non si è completato: riapri la pagina di accesso e ricontrolla il codice di verifica mostrato nel tuo terminale prima di approvare;
- Se nulla funziona, passa al “Percorso due: installazione manuale” qui sotto: sono solo tre comandi.

</details>

### Percorso due: installazione manuale

Nessun assistente IA? Nessun problema: l’intero processo si riduce a tre comandi.

**Passaggio 1: installa Tripo CLI**

Questo comando installa il comando `tripo` sul tuo computer:

```bash
npm install -g tripo-cli
```

Normalmente l’avanzamento termina senza messaggi di errore in rosso: significa che l’installazione è riuscita.

<details>
<summary><strong>Problemi?</strong> npm non trovato, o un errore di permessi</summary>

- `npm` non trovato: Node.js non è ancora installato. Installa la versione LTS corrente (20 o successiva) dal [sito di Node.js](https://nodejs.org/), poi riapri il terminale e riprova;
- Errore di permessi su macOS (EACCES): esegui invece `sudo npm install -g tripo-cli` e inserisci la password del computer quando richiesta;
- Windows dice che “l’esecuzione di script è disabilitata”: riapri PowerShell come amministratore e riprova.

</details>

**Passaggio 2: accedi al tuo account Tripo**

```bash
tripo login
```

Il browser apre automaticamente una pagina di autorizzazione (se non hai ancora un account, registrati lì prima). La pagina mostra un codice di verifica — **approvalo solo dopo aver confermato che corrisponde al codice mostrato nel tuo terminale.** Dopo l’accesso, il terminale conferma che sei connesso.

![Pagina di autorizzazione del dispositivo Tripo CLI nel browser con codice di verifica](/assets/images/docs/cli/device-authorization-en.webp)

<details>
<summary><strong>Problemi?</strong> Il browser non si è aperto, o l’accesso non si è completato</summary>

- L’accesso non si è completato: esegui di nuovo `tripo login` e approva solo dopo aver ricontrollato il codice mostrato nel tuo terminale;
- Il browser non reagisce: copia manualmente nel browser l’URL stampato nel terminale;
- L’autorizzazione nel browser è temporaneamente non disponibile: la CLI apre al suo posto la pagina della chiave API — vedi “Accesso di riserva e regioni” alla fine di questa sezione.

</details>

**Passaggio 3: verifica che tutto sia pronto**

```bash
tripo doctor
```

Controlla in sequenza lo stato dell’accesso, la connessione di rete e il saldo dei crediti. Quando tutti e tre i controlli passano, la configurazione è completa.

<details>
<summary><strong>Problemi?</strong> Uno dei controlli non è passato</summary>

- Controllo di autenticazione non superato: l’accesso non si è completato — esegui `tripo login` e accedi di nuovo;
- Controllo di rete non superato: verifica che il computer possa aprire le pagine web; le reti aziendali o universitarie potrebbero richiedere un proxy;
- Controllo del saldo non superato: non hai crediti sufficienti; non è partita alcuna generazione e non ti è stato addebitato nulla. Esegui `tripo topup` per aprire la pagina di fatturazione.

</details>

<details>
<summary><strong>Accesso di riserva e regioni</strong> (solo se l’accesso dal browser non è disponibile)</summary>

- Se hai già una chiave API, esegui `tripo login --key tsk_...` oppure imposta la variabile d’ambiente `TRIPO_API_KEY`;
- Una chiave API è una credenziale dell’account: non incollarla mai in chat, codice sorgente, screenshot o log;
- La stessa installazione funziona sia con gli account internazionali sia con quelli della Cina continentale: la CLI verifica entrambe le regioni con la tua chiave e salva automaticamente la regione che la accetta.

</details>

## Crea il tuo primo modello 3D

**Passaggio 1: genera a partire da una frase**

Le parole tra virgolette sono il tuo prompt: sostituiscile con ciò che vuoi creare:

```bash
tripo make "a cute low poly fox"
```

Tieni aperto il terminale mentre il comando è in esecuzione. Tripo CLI sceglie il workflow e il modello giusti, attende che l’attività finisca e scarica i file in una cartella `tripo-out` nella directory corrente. L’intera esecuzione di solito si conclude in pochi minuti e costa una piccola quantità di crediti.

<details>
<summary><strong>Problemi?</strong> La generazione non è partita, o si è interrotta a metà</summary>

- Crediti insufficienti: il tuo modello non ha iniziato la generazione e non ti è stato addebitato nulla. Esegui `tripo topup` per aggiungere crediti, poi riprova;
- Errore di rete: assicurati che il computer sia connesso a Internet, poi esegui di nuovo lo stesso comando;
- Attività non riuscita: gli eventuali crediti addebitati vengono rimborsati automaticamente — prova con una descrizione diversa.

</details>

**Passaggio 2: apri l’anteprima**

```bash
tripo view @last
```

`@last` significa “attività più recente”. Il browser apre un’anteprima 3D interattiva che puoi ruotare trascinando — quando vedi il tuo modello, ce l’hai fatta!

**Dopo il primo successo: che cosa hai adesso**

- **Dove sono i file**: una nuova cartella sotto `tripo-out` contiene il modello 3D scaricato e `task.json`, che registra come è stata creata l’attività; se il server fornisce un’immagine di anteprima trovi anche `preview.png`.
- **Riaprirlo**: esegui `tripo view @last` in qualsiasi momento, oppure `tripo view <file>` per aprire qualunque file di modello.
- **Quanto è costato**: esegui `tripo balance` per controllare il saldo dei crediti.
- **Odi memorizzare i comandi?** Esegui semplicemente `tripo` per aprire un menu interattivo guidato: accesso, generazione, anteprima e ricarica sono tutti lì.
- **Prossimi passi**: genera da immagini (sezione successiva), lascia guidare un assistente IA (“Lascia che gli agenti di programmazione IA padroneggino la CLI”) oppure elabora in blocco (“Workflow pronti e pipeline”).

## Genera da un’immagine o da un modello esistente

Dopo che l’esempio testuale funziona, puoi passare file locali. `concept.png`, `front.png` e `hero.glb` qui sotto sono nomi di esempio: sostituiscili con i percorsi dei tuoi file:

```bash
tripo make concept.png --for print
tripo make front.png back.png
tripo make hero.glb --then texture,rig
tripo make @last --then convert:fbx
```

- Riga 1: trasforma un’immagine concept in un modello pronto per la stampa;
- Riga 2: genera dalle immagini fronte e retro insieme, per dettagli più accurati;
- Riga 3: esegue il texturing e il rigging di un modello esistente;
- Riga 4: converte il risultato più recente in FBX.

## Lascia che gli agenti di programmazione IA padroneggino la CLI

Se non usi un agente di programmazione IA, salta questa sezione. Il pacchetto npm include un Agent Skill — riferimenti dei comandi, ricette per gli scenari e indicazioni per il recupero dagli errori — così un agente può usare la CLI correttamente. Fai eseguire all’agente questi comandi per visualizzare nel terminale le istruzioni complete o un singolo argomento:

```bash
tripo docs --llm
tripo docs --topic commands/make
tripo docs --topic examples/game-asset
```

<details>
<summary><strong>File inclusi nello Skill</strong></summary>

```text
skill/
├── SKILL.md
├── common-errors.md
├── commands/
│   ├── account.md
│   ├── batch.md
│   ├── generate.md
│   ├── make.md
│   ├── process.md
│   ├── task.md
│   └── view.md
└── examples/
    ├── animation.md
    ├── ar-web.md
    ├── film.md
    ├── game-asset.md
    ├── pipes.md
    └── print.md
```

</details>

## Riferimento dei comandi

Non serve memorizzare questa tabella: nell’uso quotidiano, ai nuovi utenti bastano `tripo` (menu interattivo), `tripo make` (generazione), `tripo view` (anteprima) e `tripo doctor` (diagnostica). Espandi il resto solo quando emerge un’esigenza specifica.

<details>
<summary><strong>Mostra la tabella completa dei comandi e le opzioni comuni</strong></summary>

| Comando | Funzione |
| --- | --- |
| `tripo make <input...>` | Genera, elabora e scarica con un solo comando |
| `tripo ai [description]` | Pianifica un lavoro, lo conferma e lo esegue |
| `tripo view [task\|file]` | Apre un'anteprima 3D locale interattiva |
| `tripo redo [task]` | Ripete una richiesta con un nuovo seed |
| `tripo login / logout / whoami / use` | Autorizza i profili account denominati e passa da uno all'altro |
| `tripo topup / balance / usage` | Apre la fatturazione regionale e controlla i crediti |
| `tripo generate <endpoint>` | Accede esplicitamente a tutti e otto gli endpoint di generazione |
| `tripo model / anim / mesh <step>` | Esegue perfezionamento, texturing, rigging, conversione, segmentazione e altri passaggi di elaborazione |
| `tripo task get/list/watch` | Interroga, elenca o attende le attività |
| `tripo history [--limit <n>]` | Mostra la cronologia locale delle attività recenti |
| `tripo files upload <path>` | Carica un file e ne restituisce il `file_token` |
| `tripo batch run <manifest.yaml>` | Esegue pipeline in blocco ripristinabili, con concorrenza e nuovi tentativi |
| `tripo config / doctor` | Gestisce le impostazioni e diagnostica l'ambiente locale |
| `tripo docs [--topic <topic>]` | Visualizza la documentazione inclusa dell'Agent e dei comandi |
| `tripo mcp` | Esegue la CLI come server MCP |
| `tripo completion <shell>` | Genera il completamento per Bash, Zsh o Fish |

I comandi `make`, `ai` e `generate`, insieme ai sottocomandi di elaborazione di `model`, `anim` e `mesh`, supportano `-o/--out`, `--no-wait`, `--no-download`, `--name`, `--timeout`, `--notify` e l'opzione ripetibile `--param key=value`. Le opzioni globali di automazione includono `--json`, `--yes`, `--quiet`, `--no-open` e `--profile`.

</details>

## Workflow pronti e pipeline

Questa sezione è avanzata e non serve per la prima generazione. Sette preimpostazioni integrate applicano in una volta parametri e passaggi di elaborazione utili tramite `--for <preset>`:

`game-mobile` · `game-pc` · `film` · `print` · `ar-web` · `anim` · `toy`

```bash
# Mobile game asset: low-poly generation, texture, then FBX
tripo make "sci-fi crate" --for game-mobile

# Print asset: watertight output, STL, and a flat bottom
tripo make "chess knight" --for print

# Explicit processing chain
tripo make cat.png --then texture,rig,convert:fbx

# The same chain as NDJSON pipes
tripo make cat.png --json | tripo model texture --json | tripo anim rig --json

# Resumable batch processing
tripo batch run assets.yaml --concurrency 2
```

I riferimenti alle attività come `@last`, `@2` e `@name` funzionano ovunque sia accettato un ID attività.

## Più account e regioni

Se usi un solo account Tripo, salta questa sezione. Le credenziali vengono archiviate in profili denominati, quindi l'accesso a un secondo account non sovrascrive il primo:

```bash
tripo login
tripo login --profile work-cn
tripo use
tripo whoami
tripo make "a fox" --profile work-cn
tripo logout
```

Ogni profilo conserva la propria chiave e la propria regione. La variabile d’ambiente `TRIPO_PROFILE` seleziona un profilo per l’ambiente corrente, mentre `TRIPO_API_KEY` ignora tutti i profili e ha la priorità più alta.

## Note per gli agenti di programmazione IA

Gli utenti umani possono saltare questa sezione. Queste regole aiutano un agente di programmazione IA ad attendere correttamente le attività e a leggere l’output elaborabile dalle macchine.

- `tripo make` e `tripo task watch` sono comandi bloccanti. Attendi il completamento del processo invece di implementare un altro ciclo di polling.
- Con `--json`, la maggior parte dei comandi eseguiti una sola volta scrive una riga JSON finale in stdout. `tripo task watch --json`, invece, trasmette eventi di avanzamento NDJSON seguiti dal risultato finale.
- Se `preview.png` esiste, controllalo prima di decidere se proseguire una pipeline o eseguire `tripo redo`.
- Non inventare parametri e non forzare versioni di modelli precedenti. Usa `tripo docs --topic ...` per conoscere le opzioni supportate.
- Una richiesta low-poly o un budget massimo di 20.000 facce seleziona `tripo-p1`; gli altri lavori usano `tripo-v3.1` per impostazione predefinita.

<details>
<summary><strong>Mostra la tabella dei codici di uscita</strong></summary>

| Codice di uscita | Significato |
| --- | --- |
| `0` | Operazione riuscita |
| `1` | Errore imprevisto o interno |
| `2` | Utilizzo o parametri non validi |
| `3` | Errore di autenticazione |
| `4` | Crediti insufficienti |
| `5` | Rifiuto in base alle norme sui contenuti |
| `6` | Attività non riuscita; i crediti vengono rimborsati automaticamente |
| `7` | Errore di rete |
| `8` | Risorsa non trovata |
| `9` | Limite di frequenza raggiunto; riprova con backoff |

</details>

## Variabili d’ambiente per l’automazione

Le variabili d’ambiente non servono per l’uso interattivo normale: esistono per CI, script e workflow avanzati con agenti. Ricorda: non eseguire mai il commit di una chiave API in un repository, non incollarla nella documentazione e non includerla in screenshot o log.

<details>
<summary><strong>Mostra la tabella delle variabili d’ambiente</strong></summary>

| Variabile | Scopo |
| --- | --- |
| `TRIPO_API_KEY` | Chiave API; massima priorità e adatta per CI o Agent |
| `TRIPO_PROFILE` | Profilo account denominato, equivalente a `--profile` |
| `TRIPO_REGION` | Override facoltativo `ov` o `cn`; normalmente rilevato automaticamente |
| `TRIPO_API_BASE_URL` | Override dell'endpoint API |
| `TRIPO_PLATFORM_BASE_URL` | Override dell'endpoint della piattaforma |
| `TRIPO_HOME` | Directory di configurazione e cronologia; il valore predefinito è `~/.tripo` |
| `TRIPO_LLM_BASE_URL` | Endpoint facoltativo compatibile con OpenAI per `tripo ai` |
| `TRIPO_LLM_API_KEY` | Chiave LLM facoltativa per `tripo ai` |
| `TRIPO_LLM_MODEL` | Modello LLM facoltativo per `tripo ai` |

</details>