Meshy CLI

Erstellen, verfolgen und laden Sie Meshy-Modelle direkt von Ihrem Terminal aus herunter. Ein einziger Befehl verwandelt einen prompt oder ein Bild in ein texturiertes Modell, und die meisten API-Endpunkte sind eigene Befehle.

Die Meshy CLI (meshy) ruft dieselbe REST-API auf wie der Rest dieser Dokumentation, zu denselben Preisen. Sie melden sich einmal in Ihrem Browser an, sodass Sie keinen API-Schlüssel benötigen. In einem Terminal gibt sie eine lesbare Ansicht aus, und in einem Skript, einer Pipe, CI oder einem KI-Agenten gibt sie JSON aus.

Installation

Die CLI benötigt Node.js 22.12 oder höher. Sie läuft unter macOS, Linux und Windows.

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

Das Paket installiert zwei Befehle, meshy und meshy-cli. Derselbe Build wird auch als @meshy-ai/cli veröffentlicht. Installieren Sie nur eines der beiden Pakete, da beide den Befehl meshy bereitstellen und npm das zweite mit EEXIST ablehnt.

Die CLI ist Open Source. Ihr Quellcode befindet sich im meshy-cli-Repository auf GitHub.

Anmelden

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

meshy auth login öffnet eine Meshy-Anmeldeseite in Ihrem Browser und speichert die Anmeldedaten auf Ihrem Computer. Falls sich der Browser nicht öffnet, kopieren Sie die URL, die die CLI ausgibt.

Remote-Rechner, SSH und Container

Auf einem Rechner ohne Browser gibt meshy auth login stattdessen einen Link und einen kurzen Code aus. Öffnen Sie den Link auf einem beliebigen Gerät, zum Beispiel Ihrem Laptop oder Smartphone, melden Sie sich an und geben Sie den Code ein. Die CLI schließt die Anmeldung selbstständig ab.

Die CLI wählt diesen Ablauf, wenn sie SSH, einen Container, CI, Linux ohne Anzeige oder kein interaktives Terminal erkennt, etwa wenn ein KI-Agent den Befehl ausführt. Sie wählt ihn auch, wenn MESHY_CLI_NO_BROWSER gesetzt ist. Um ihn selbst auszuwählen, führen Sie meshy auth login --device aus.

meshy auth login --device

API-Schlüssel und CI

Für CI und andere unbeaufsichtigte Aufgaben verwenden Sie einen API-Schlüssel anstelle einer Browser-Anmeldung. Legen Sie ihn in der Umgebungsvariable MESHY_API_KEY fest. Er hat Priorität gegenüber einer gespeicherten Anmeldung.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Sie können einen Schlüssel auch mit meshy auth login --with-key msy_YOUR_API_KEY speichern.

Die CLI verwendet die erste gefundene Anmeldeinformation in dieser Reihenfolge: --api-key, MESHY_API_KEY, --api-key-file, dann die gespeicherte Anmeldung. Wenn die CLI ein anderes Konto als erwartet verwendet, führen Sie meshy auth status aus, um zu sehen, welche Anmeldeinformation aktuell gilt.

China-Website

Ein Meshy-Konto funktioniert auf beiden Websites. Um meshy.cn zu nutzen, melden Sie sich mit meshy auth login --region cn an. Die CLI speichert die Region zusammen mit Ihrer Anmeldung, sodass spätere Befehle api.meshy.cn ohne zusätzliches Flag aufrufen. Um zurückzuwechseln, melden Sie sich mit --region global an.

Erstellen Sie Ihr erstes Modell

meshy make führt den gesamten Ablauf in einem einzigen Befehl aus. Ein Text-prompt startet eine Text zu 3D-Vorschau und anschließend ein refine. Ein Bild startet eine einzelne texturierte Bild zu 3D-Aufgabe.

Prüfen Sie zunächst, was ein Durchlauf bewirken würde und wie viele Credits er kosten würde, ohne dabei welche auszugeben:

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

Führen Sie es dann aus und speichern Sie das Modell mit -o in einem Ordner:

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

Der Ordner enthält nun das Modell, seine Miniaturansicht und eine meta.json-Datei. Um stattdessen von einem Foto auszugehen, übergeben Sie dessen Pfad oder URL: meshy make ./cat.png -o out/cat/.

Commands

Die meisten API-Endpunkte sind selbst eigenständige Befehle, und jeder Task-Befehl verwendet dieselben Verben: create, get, list, wait, stream und delete. Für einen Endpunkt ohne eigenen Befehl verwenden Sie meshy api.

Diese Befehle decken die gängigen Aufgaben ab:

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

Die Flags eines Befehls erhalten Sie mit meshy <resource> --help. Die Parameter und Credit-Kosten der einzelnen Endpunkte finden Sie auf der jeweiligen Seite dieser Dokumentation, wie z. B. Text zu 3D.

Die CLI verfügt außerdem über lokale Hilfsprogramme für den 3D-Druck, wie meshy inspect faces, meshy mesh prepare-print und meshy slicer. Diese laufen auf Ihrem Computer und rufen die API nicht auf. Eine vollständige Übersicht aller Befehle finden Sie unter Using meshy-cli.

Skripte, Agenten und CI

JSON-Ausgabe

Wenn die Ausgabe an eine Pipe, eine Datei, ein Skript oder einen KI-Agenten geht, gibt die CLI JSON aus. In einem Terminal zeigt sie eine lesbare Ansicht an. Übergeben Sie --format json (oder --json), um immer JSON zu erhalten.

Jeder Befehl gibt genau ein JSON-Dokument auf stdout aus, mit denselben sechs Schlüsseln. Fortschritt und Meldungen gehen an 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 gibt an, ob der CLI-Befehl funktioniert hat. Der eigene Zustand des Tasks steht in result.task.status. Zum Beispiel gibt get bei einem fehlgeschlagenen Task ok: true zurück, da die Anfrage selbst funktioniert hat.

Die CLI sendet jede Create-Anfrage einmal und wiederholt sie nie von sich aus, sodass ein Netzwerkfehler nicht einen zweiten Task erstellen und berechnen kann.

Exit-Codes

Der Exit-Code sagt einem Skript, was passiert ist:

Für die Codes 11 bis 14 und das vollständige Ausgabeformat siehe Skripte und Agenten.

GitHub Actions

Speichern Sie Ihren API-Schlüssel als Repository-Secret mit dem Namen MESHY_API_KEY und führen Sie die CLI dann in einem Job aus:

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/

Der Schritt schlägt fehl, wenn die CLI mit einem von null verschiedenen Code beendet wird.

KI-Agenten

Jeder Agent, der Shell-Befehle ausführen kann, kann die CLI nutzen, einschließlich Claude Code, Cursor und Codex. Der Agent erhält JSON automatisch.

Um Ihrem Agenten die Meshy-Workflows beizubringen, installieren Sie das Open-Source-Skill-Paket meshy-3d-agent. Es läuft auf der CLI.

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

Referenz

Globale Flags

Diese Flags funktionieren bei jedem Befehl:

Umgebungsvariablen

Die CLI liest diese Variablen:

Wo Zugangsdaten gespeichert werden

Die CLI speichert Zugangsdaten in ~/.config/meshy/credentials.v2.json, die nur von Ihnen gelesen werden kann. Das darin enthaltene Zugangsdatum ist mit einem Schlüssel verschlüsselt, der im Schlüsselanhänger des Betriebssystems aufbewahrt wird: Keychain unter macOS, DPAPI unter Windows oder der Secret Service unter Linux. Wo kein Schlüsselanhänger verfügbar ist, etwa in einem Container oder über SSH, ist der Schlüssel eine Datei neben den Zugangsdaten.

Updates und Deinstallation

Die CLI prüft höchstens einmal täglich bei npm auf eine neue Version und informiert Sie darüber auf stderr. Ihre stdout-Ausgabe wird dabei nie verändert. Jede API-Anfrage enthält einen User-Agent-Header mit der CLI-Version, Ihrem Betriebssystem und dem KI-Agenten, der die CLI ausführt, sofern einer erkannt wird. Um den Agenten wegzulassen, setzen Sie MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

Um zu sehen, was sich in jeder Version geändert hat, siehe die Releases auf GitHub.

Fehlerbehebung

Führen Sie zunächst meshy doctor aus. Es prüft Ihre Einrichtung, ohne die API aufzurufen. Dies sind die häufigsten Probleme:

Um einen Fehler zu melden, öffnen Sie ein Issue im meshy-cli-Repository.

Nächste Schritte

• Sehen Sie die Parameter und Kosten jedes Endpunkts in der API-Referenz.
• Vergleichen Sie die CLI mit dem MCP-Server in KI-Integration.
• Lesen Sie Using meshy-cli für alle Befehle und Flags.