Meshy CLI

Générez, suivez et téléchargez des modèles Meshy depuis votre terminal. Une seule commande transforme un prompt ou une image en modèle texturé, et la plupart des points de terminaison API sont des commandes à part entière.

Le Meshy CLI (meshy) appelle la même API REST que le reste de cette documentation, aux mêmes tarifs. Vous vous connectez une seule fois dans votre navigateur, donc vous n'avez pas besoin de clé API. Dans un terminal, il affiche une vue lisible, et dans un script, un pipe, une CI ou un agent IA, il affiche du JSON.

Install

La CLI nécessite Node.js 22.12 ou une version ultérieure. Elle fonctionne sur macOS, Linux et Windows.

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

Le package installe deux commandes, meshy et meshy-cli. La même version est également publiée sous le nom @meshy-ai/cli. N'installez qu'un seul des deux packages, car les deux fournissent la commande meshy et npm refuse le second avec EEXIST.

La CLI est open source. Son code source se trouve dans le dépôt meshy-cli sur GitHub.

Se connecter

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

meshy auth login ouvre une page de connexion Meshy dans votre navigateur et enregistre l'identifiant sur votre ordinateur. Si le navigateur ne s'ouvre pas, copiez l'URL affichée par la CLI.

Machines distantes, SSH et conteneurs

Sur une machine sans navigateur, meshy auth login affiche à la place un lien et un code court. Ouvrez le lien sur n'importe quel appareil, comme votre ordinateur portable ou votre téléphone, connectez-vous et saisissez le code. La CLI termine la connexion toute seule.

La CLI choisit ce mode de fonctionnement lorsqu'elle détecte SSH, un conteneur, un environnement CI, Linux sans affichage, ou aucun terminal interactif, comme lorsqu'un agent IA exécute la commande. Elle le choisit également lorsque MESHY_CLI_NO_BROWSER est défini. Pour le choisir vous-même, exécutez meshy auth login --device.

meshy auth login --device

Clés API et CI

Pour les tâches CI et autres jobs non surveillés, utilisez une clé API plutôt qu'une connexion par navigateur. Définissez-la dans la variable d'environnement MESHY_API_KEY. Elle a priorité sur une connexion enregistrée.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Vous pouvez également stocker une clé avec meshy auth login --with-key msy_YOUR_API_KEY.

Le CLI utilise le premier identifiant qu'il trouve, dans cet ordre : --api-key, MESHY_API_KEY, --api-key-file, puis la connexion enregistrée. Si le CLI utilise un compte différent de celui que vous attendiez, exécutez meshy auth status pour voir quel identifiant est actuellement utilisé.

Site chinois

Un seul compte Meshy fonctionne sur les deux sites. Pour utiliser meshy.cn, connectez-vous avec meshy auth login --region cn. Le CLI enregistre la région avec votre connexion, ainsi les commandes ultérieures appellent api.meshy.cn sans option. Pour revenir en arrière, connectez-vous avec --region global.

Créez votre premier modèle

meshy make exécute l'ensemble du flux en une seule commande. Un prompt textuel exécute un aperçu Texte en 3D puis un refine. Une image exécute une seule tâche Image en 3D texturée.

D'abord, vérifiez ce qu'une exécution fera et combien de crédits elle coûtera, sans en dépenser :

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

Puis exécutez-la, et enregistrez le modèle dans un dossier avec -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

Le dossier contient désormais le modèle, sa miniature, et un fichier meta.json. Pour partir d'une photo à la place, indiquez son chemin ou son URL : meshy make ./cat.png -o out/cat/.

Commands

La plupart des points de terminaison API sont des commandes à part entière, et chaque commande de tâche utilise les mêmes verbes : create, get, list, wait, stream et delete. Pour un point de terminaison sans commande dédiée, utilisez meshy api.

Ces commandes couvrent les tâches courantes :

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

Pour connaître les options d'une commande, exécutez meshy <resource> --help. Pour les paramètres et les coûts en crédits de chaque point de terminaison, consultez sa page dans cette documentation, comme Texte en 3D.

Le CLI dispose également d'utilitaires locaux pour l'impression 3D, comme meshy inspect faces, meshy mesh prepare-print et meshy slicer. Ils s'exécutent sur votre ordinateur et n'appellent pas l'API. Consultez Using meshy-cli pour la liste complète des commandes.

Scripts, agents et CI

Sortie JSON

Lorsque sa sortie est dirigée vers un pipe, un fichier, un script ou un agent IA, le CLI affiche du JSON. Dans un terminal, il affiche une vue lisible. Passez --format json (ou --json) pour toujours obtenir du JSON.

Chaque commande affiche exactement un document JSON sur stdout, avec les mêmes six clés. La progress et les messages sont envoyés sur 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 indique si la commande CLI a fonctionné. L'état propre de la tâche se trouve dans result.task.status. Par exemple, get sur une tâche ayant échoué renvoie ok: true, car la requête elle-même a fonctionné.

Le CLI envoie chaque requête de création une seule fois et ne la retente jamais de lui-même, de sorte qu'une erreur réseau ne peut pas créer, et facturer, une seconde tâche.

Codes de sortie

Le code de sortie indique à un script ce qui s'est passé :

Pour les codes 11 à 14 et le format de sortie complet, consultez Scripts et agents.

GitHub Actions

Stockez votre clé API en tant que secret de dépôt nommé MESHY_API_KEY, puis exécutez la CLI dans 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/

L'étape échoue lorsque la CLI se termine avec un code différent de zéro.

Agents IA

Tout agent capable d'exécuter des commandes shell peut utiliser la CLI, y compris Claude Code, Cursor et Codex. L'agent obtient automatiquement du JSON.

Pour enseigner les workflows Meshy à votre agent, installez le pack de compétences open-source meshy-3d-agent. Il fonctionne sur la CLI.

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

Référence

Indicateurs globaux

Ces indicateurs fonctionnent sur chaque commande :

Variables d'environnement

Le CLI lit ces variables :

Où sont stockées les identifiants

La CLI stocke les identifiants dans ~/.config/meshy/credentials.v2.json, lisible uniquement par vous. L'identifiant qu'il contient est chiffré avec une clé conservée dans le porte-clés du système d'exploitation : Keychain sur macOS, DPAPI sur Windows, ou le Secret Service sur Linux. Lorsqu'aucun porte-clés n'est disponible, comme dans un conteneur ou via SSH, la clé est un fichier situé à côté des identifiants.

Mises à jour et désinstallation

La CLI vérifie sur npm l'existence d'une nouvelle version au plus une fois par jour et vous en informe sur stderr. Elle ne modifie jamais votre stdout. Chaque requête API porte un en-tête User-Agent contenant la version de la CLI, votre système d'exploitation, et l'agent IA exécutant la CLI, s'il en détecte un. Pour omettre l'agent, définissez MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

Pour voir ce qui a changé dans chaque version, consultez les releases sur GitHub.

Dépannage

Exécutez d'abord meshy doctor. Il vérifie votre configuration sans appeler l'API. Voici les problèmes courants :

Pour signaler un bug, ouvrez un ticket dans le dépôt meshy-cli.

Étapes suivantes

• Consultez les paramètres et les coûts de chaque point de terminaison dans la référence API.
• Comparez le CLI avec le MCP server dans Intégration IA.
• Lisez Using meshy-cli pour toutes les commandes et options.