Meshy CLI

Genereer, volg en download Meshy-modellen vanuit je terminal. Eén commando zet een prompt of een afbeelding om in een getextureerd model, en de meeste API-endpoints zijn zelf ook commando's.

De Meshy CLI (meshy) roept dezelfde REST API aan als de rest van deze documentatie, tegen dezelfde prijzen. Je logt eenmalig in via je browser, dus je hebt geen API-sleutel nodig. In een terminal toont het een leesbare weergave, en in een script, een pipe, CI, of een AI-agent toont het JSON.

Install

De CLI vereist Node.js 22.12 of hoger. Hij draait op macOS, Linux en Windows.

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

Het package installeert twee commando's, meshy en meshy-cli. Dezelfde build wordt ook gepubliceerd als @meshy-ai/cli. Installeer slechts één van de twee packages, want beide bieden het meshy-commando aan en npm weigert het tweede met EEXIST.

De CLI is open source. De broncode staat in de meshy-cli-repository op GitHub.

Inloggen

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

meshy auth login opent een Meshy-inlogpagina in je browser en slaat de referentie op je computer op. Als de browser niet opent, kopieer dan de URL die de CLI weergeeft.

Externe machines, SSH en containers

Op een machine zonder browser geeft meshy auth login in plaats daarvan een link en een korte code weer. Open de link op een willekeurig apparaat, zoals je laptop of telefoon, log in en voer de code in. De CLI rondt het inloggen zelfstandig af.

De CLI kiest deze flow wanneer deze SSH, een container, CI, Linux zonder beeldscherm of geen interactieve terminal detecteert, zoals wanneer een AI-agent de opdracht uitvoert. De CLI kiest deze flow ook wanneer MESHY_CLI_NO_BROWSER is ingesteld. Om de flow zelf te kiezen, voer je meshy auth login --device uit.

meshy auth login --device

API-sleutels en CI

Gebruik voor CI en andere taken zonder toezicht een API-sleutel in plaats van een browser-login. Stel deze in via de omgevingsvariabele MESHY_API_KEY. Dit heeft prioriteit boven een opgeslagen login.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Je kunt ook een sleutel opslaan met meshy auth login --with-key msy_YOUR_API_KEY.

De CLI gebruikt de eerste credential die hij vindt, in deze volgorde: --api-key, MESHY_API_KEY, --api-key-file, en daarna de opgeslagen login. Als de CLI een ander account gebruikt dan je verwacht, voer dan meshy auth status uit om te zien welke credential actief is.

China-site

Eén Meshy-account werkt op beide sites. Om meshy.cn te gebruiken, meld je je aan met meshy auth login --region cn. De CLI slaat de regio op bij je aanmelding, zodat latere commando's api.meshy.cn aanroepen zonder vlag. Om terug te schakelen, meld je je aan met --region global.

Maak je eerste model

meshy make voert de hele flow in één commando uit. Een tekst-prompt voert een Tekst naar 3D-preview uit en daarna een refine. Een afbeelding voert één getextureerde Afbeelding naar 3D-taak uit.

Controleer eerst wat een run zal doen en hoeveel credits het zal kosten, zonder er iets van uit te geven:

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

Voer het vervolgens uit en sla het model op in een map met -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

De map bevat nu het model, de thumbnail ervan en een meta.json-bestand. Om in plaats daarvan vanuit een foto te beginnen, geef je het pad of de URL ervan op: meshy make ./cat.png -o out/cat/.

Commands

De meeste API-endpoints zijn zelf commando's, en elk taakcommando gebruikt dezelfde werkwoorden: create, get, list, wait, stream en delete. Voor een endpoint zonder eigen commando gebruik je meshy api.

Deze commando's dekken de meest voorkomende taken:

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

Voor de flags van een commando voer je meshy <resource> --help uit. Voor de parameters en credit-kosten van elke endpoint, zie de bijbehorende pagina in deze documentatie, zoals Tekst naar 3D.

De CLI heeft ook lokale hulpmiddelen voor 3D-printen, zoals meshy inspect faces, meshy mesh prepare-print en meshy slicer. Deze draaien op je eigen computer en roepen de API niet aan. Zie Using meshy-cli voor alle commando's.

Scripts, agents en CI

JSON-output

Wanneer de uitvoer naar een pipe, een bestand, een script of een AI-agent gaat, drukt de CLI JSON af. In een terminal toont deze een leesbare weergave. Geef --format json (of --json) mee om altijd JSON te krijgen.

Elke opdracht drukt precies één JSON-document af op stdout, met dezelfde zes sleutels. Voortgang en meldingen gaan naar 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 geeft aan of de CLI-opdracht is gelukt. De eigen status van de taak staat in result.task.status. Zo geeft get voor een mislukte taak ok: true terug, omdat het verzoek zelf wel werkte.

De CLI verstuurt elk create-verzoek precies één keer en probeert dit nooit opnieuw, zodat een netwerkfout niet kan leiden tot het aanmaken van, en het in rekening brengen van, een tweede taak.

Afsluitcodes

De afsluitcode vertelt een script wat er is gebeurd:

Voor codes 11 tot 14 en het volledige uitvoerformaat, zie Scripts en agents.

GitHub Actions

Sla je API-sleutel op als repository secret met de naam MESHY_API_KEY, en voer de CLI vervolgens uit in een 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/

De stap mislukt wanneer de CLI afsluit met een niet-nul exitcode.

AI-agents

Elke agent die shell-commando's kan uitvoeren, kan de CLI gebruiken, waaronder Claude Code, Cursor en Codex. De agent krijgt automatisch JSON.

Om je agent de Meshy-workflows aan te leren, installeer je de opensource meshy-3d-agent skill pack. Deze draait op de CLI.

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

Referentie

Algemene vlaggen

Deze vlaggen werken bij elk commando:

Omgevingsvariabelen

De CLI leest deze variabelen:

Waar inloggegevens worden opgeslagen

De CLI slaat inloggegevens op in ~/.config/meshy/credentials.v2.json, alleen leesbaar door jou. De inloggegevens daarin zijn versleuteld met een sleutel die bewaard wordt in de OS-sleutelhanger: Keychain op macOS, DPAPI op Windows, of de Secret Service op Linux. Waar geen sleutelhanger beschikbaar is, zoals in een container of via SSH, is de sleutel een bestand naast de inloggegevens.

Updates en verwijderen

De CLI controleert hooguit één keer per dag bij npm op een nieuwe versie en meldt dit via stderr. Je stdout wordt nooit aangepast. Elk API-verzoek bevat een User-Agent-header met de CLI-versie, je besturingssysteem en de AI-agent die de CLI uitvoert, indien gedetecteerd. Om de agent weg te laten, stel je MESHY_CLI_AGENT=none in.

npm install -g meshy-cli@latest

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

Zie de releases op GitHub om te zien wat er in elke versie is veranderd.

Probleemoplossing

Voer eerst meshy doctor uit. Dit controleert je configuratie zonder de API aan te roepen. Dit zijn de meest voorkomende problemen:

Om een bug te rapporteren, open je een issue in de meshy-cli repository.

Volgende stappen

• Bekijk de parameters en kosten van elke endpoint in de API-referentie.
• Vergelijk de CLI met de MCP server in AI-integratie.
• Lees Using meshy-cli voor elk commando en elke flag.