Meshy CLI

Genera, monitora e scarica modelli Meshy direttamente dal tuo terminale. Un singolo comando trasforma un prompt o un'immagine in un modello texturizzato, e la maggior parte degli endpoint API sono a loro volta comandi.

La Meshy CLI (meshy) richiama la stessa API REST del resto di questa documentazione, agli stessi prezzi. Accedi una sola volta dal tuo browser, quindi non hai bisogno di una chiave API. In un terminale mostra una vista leggibile, mentre in uno script, in una pipe, in CI o in un agente AI restituisce JSON.

Install

La CLI richiede Node.js 22.12 o versioni successive. Funziona su macOS, Linux e Windows.

npm install -g meshy-cli
meshy doctor    # checks your environment, without calling the API

Il pacchetto installa due comandi, meshy e meshy-cli. La stessa build è pubblicata anche come @meshy-ai/cli. Installa solo uno dei due pacchetti, perché entrambi forniscono il comando meshy e npm rifiuta il secondo con EEXIST.

La CLI è open source. Il suo codice sorgente si trova nel repository meshy-cli su GitHub.

Sign in

meshy auth login     # opens your browser
meshy auth status    # shows which account and credential are in use

meshy auth login apre una pagina di accesso a Meshy nel tuo browser e memorizza la credenziale sul tuo computer. Se il browser non si apre, copia l'URL stampato dalla CLI.

Macchine remote, SSH e container

Su una macchina senza browser, meshy auth login stampa invece un link e un codice breve. Apri il link su qualsiasi dispositivo, ad esempio il tuo laptop o telefono, accedi e inserisci il codice. La CLI completa l'accesso autonomamente.

La CLI sceglie questo flusso quando rileva SSH, un container, CI, Linux senza display, oppure l'assenza di un terminale interattivo, come quando un agente AI esegue il comando. Lo sceglie anche quando è impostata la variabile MESHY_CLI_NO_BROWSER. Per sceglierlo tu stesso, esegui meshy auth login --device.

meshy auth login --device

Chiavi API e CI

Per la CI e altri job non presidiati, usa una chiave API invece dell'accesso tramite browser. Impostala nella variabile d'ambiente MESHY_API_KEY. Ha la priorità rispetto a un accesso salvato.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Puoi anche salvare una chiave con meshy auth login --with-key msy_YOUR_API_KEY.

La CLI utilizza la prima credenziale che trova, in quest'ordine: --api-key, MESHY_API_KEY, --api-key-file, poi l'accesso salvato. Se la CLI utilizza un account diverso da quello previsto, esegui meshy auth status per vedere quale credenziale è attiva.

Sito Cina

Un unico account Meshy funziona su entrambi i siti. Per usare meshy.cn, accedi con meshy auth login --region cn. La CLI memorizza la regione insieme al tuo accesso, così i comandi successivi chiamano api.meshy.cn senza bisogno di alcun flag. Per tornare indietro, accedi con --region global.

Crea il tuo primo modello

meshy make esegue l'intero flusso con un solo comando. Un prompt testuale avvia un'anteprima Testo in 3D seguita da un refine. Un'immagine avvia un'unica attività Immagine in 3D con texture.

Per prima cosa, controlla cosa farà un'esecuzione e quanti crediti costerà, senza spenderne alcuno:

meshy make "a lovely baby husky" --dry-run

Poi eseguila, e salva il modello in una cartella con -o:

meshy make "a lovely baby husky" -o out/husky/

✓ [1/2] text-to-3d preview (geometry)                 01a0c94c-…   1m 27s
✓ [2/2] text-to-3d refine (textures)                  01a0c94d-…   5m 36s

✓ SUCCEEDED  text-to-3d-refine
Task     01a0c94d-eaba-710e-b5b7-da5b2f620c95
Created  2026-11-13 10:02
Took     7m 03s
Credits  ~30 (estimate for the whole chain)
Assets   glb, fbx · textures: base_color, metallic, normal, roughness · thumbnail
Saved    out/husky/model.glb
         out/husky/thumbnail.png
         out/husky/meta.json

La cartella ora contiene il modello, la sua miniatura e un file meta.json. Per partire invece da una foto, passa il suo percorso o URL: meshy make ./cat.png -o out/cat/.

Comandi

La maggior parte degli endpoint API sono comandi a sé stanti, e ogni comando di task utilizza gli stessi verbi: create, get, list, wait, stream e delete. Per un endpoint senza un proprio comando, usa meshy api.

Questi comandi coprono le attività più comuni:

meshy text-to-3d create --mode preview --prompt "a red sports car"
meshy image-to-3d create --image-url ./cat.png --async    # returns the task ID at once
meshy image-to-3d wait <task-id> -o out/cat/
meshy text-to-3d list
meshy download --resource text-to-3d --task-id <task-id> --list
meshy balance

Per conoscere i flag di un comando, esegui meshy <resource> --help. Per i parametri e i costi in crediti di ciascun endpoint, consulta la relativa pagina in questa documentazione, ad esempio Testo in 3D.

La CLI dispone anche di strumenti locali per la stampa 3D, come meshy inspect faces, meshy mesh prepare-print e meshy slicer. Vengono eseguiti sul tuo computer e non chiamano l'API. Consulta Using meshy-cli per l'elenco completo dei comandi.

Scripts, agent e CI

Output JSON

Quando il suo output è diretto verso una pipe, un file, uno script o un agente AI, la CLI stampa JSON. In un terminale stampa una vista leggibile. Passa --format json (o --json) per ottenere sempre JSON.

Ogni comando stampa esattamente un documento JSON su stdout, con le stesse sei chiavi. Progress e messaggi vanno su stderr.

meshy text-to-3d create --mode preview --prompt "a cactus" --async --format json \
  | jq -r .result.submission.task_id

{
  "schema_version": "meshy.cli/v1",
  "command": "image-to-3d.get",
  "ok": true,
  "result": { "task": { "task_id": "…", "status": "IN_PROGRESS", "progress": 52 } },
  "error": null,
  "warnings": []
}

ok indica se il comando CLI ha funzionato. Lo stato del task è in result.task.status. Ad esempio, get su un task fallito restituisce ok: true, perché la richiesta stessa ha funzionato.

La CLI invia ogni richiesta di creazione una sola volta e non la ritenta mai autonomamente, così un errore di rete non può creare, e addebitare, un secondo task.

Codici di uscita

Il codice di uscita indica a uno script cosa è successo:

Per i codici da 11 a 14 e il formato completo dell'output, vedi Script e agenti.

GitHub Actions

Salva la tua chiave API come segreto del repository con il nome MESHY_API_KEY, quindi esegui la CLI in un job:

name: Generate a model
on: workflow_dispatch

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g meshy-cli
      - run: meshy make "a low-poly treasure chest" -o assets/chest/ --format json
        env:
          MESHY_API_KEY: ${{ secrets.MESHY_API_KEY }}
      - uses: actions/upload-artifact@v4
        with:
          name: chest
          path: assets/chest/

Lo step fallisce quando la CLI termina con un codice diverso da zero.

Agenti AI

Qualsiasi agente in grado di eseguire comandi shell può usare la CLI, inclusi Claude Code, Cursor e Codex. L'agente riceve automaticamente JSON.

Per insegnare al tuo agente i flussi di lavoro di Meshy, installa il pacchetto di skill open-source meshy-3d-agent. Funziona sulla CLI.

npx skills add meshy-dev/meshy-3d-agent

Riferimento

Flag globali

Questi flag funzionano su ogni comando:

Variabili d'ambiente

La CLI legge queste variabili:

Dove vengono archiviate le credenziali

La CLI archivia le credenziali in ~/.config/meshy/credentials.v2.json, leggibile solo da te. La credenziale al suo interno è crittografata con una chiave conservata nel portachiavi del sistema operativo: Keychain su macOS, DPAPI su Windows, o Secret Service su Linux. Dove non è disponibile alcun portachiavi, ad esempio in un container o tramite SSH, la chiave è un file accanto alle credenziali.

Aggiornamenti e disinstallazione

La CLI controlla su npm la presenza di una nuova versione al massimo una volta al giorno e te lo comunica su stderr. Non modifica mai il tuo stdout. Ogni richiesta API trasporta un header User-Agent con la versione della CLI, il tuo sistema operativo, e l'agente AI che esegue la CLI, se ne rileva uno. Per escludere l'agente, imposta MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

meshy auth logout --all       # deletes the stored credentials
npm uninstall -g meshy-cli

Per vedere cosa è cambiato in ogni versione, consulta le release su GitHub.

Risoluzione dei problemi

Esegui prima meshy doctor. Controlla la tua configurazione senza chiamare l'API. Questi sono i problemi più comuni:

Per segnalare un bug, apri un issue nel repository meshy-cli.

Prossimi passi

• Consulta i parametri e i costi di ogni endpoint nella documentazione dell'API.
• Confronta la CLI con l'MCP server in Integrazione AI.
• Leggi Using meshy-cli per tutti i comandi e le opzioni.