Meshy CLI

Generera, följ och ladda ner Meshy-modeller direkt från din terminal. Ett enda kommando omvandlar en prompt eller en bild till en texturerad modell, och de flesta API-endpoints är kommandon i sig själva.

Meshy CLI (meshy) anropar samma REST-API som resten av denna dokumentation, till samma priser. Du loggar in en gång i din webbläsare, så du behöver ingen API-nyckel. I en terminal skrivs en lättläst vy ut, och i ett skript, en pipe, CI eller en AI-agent skrivs JSON ut.

Installera

CLI:n kräver Node.js 22.12 eller senare. Den körs på macOS, Linux och Windows.

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

Paketet installerar två kommandon, meshy och meshy-cli. Samma build publiceras även som @meshy-ai/cli. Installera bara ett av de två paketen, eftersom båda tillhandahåller kommandot meshy och npm nekar det andra med EEXIST.

CLI:n är öppen källkod. Källkoden finns i meshy-cli-repositoriet på GitHub.

Logga in

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

meshy auth login öppnar en Meshy-inloggningssida i din webbläsare och sparar autentiseringsuppgiften på din dator. Om webbläsaren inte öppnas, kopiera URL:en som CLI:t skriver ut.

Fjärrdatorer, SSH och containrar

På en dator utan webbläsare skriver meshy auth login istället ut en länk och en kort kod. Öppna länken på valfri enhet, till exempel din bärbara dator eller telefon, logga in och ange koden. CLI:t slutför inloggningen på egen hand.

CLI:t väljer detta flöde när det upptäcker SSH, en container, CI, Linux utan skärm, eller ingen interaktiv terminal, till exempel när en AI-agent kör kommandot. Det väljer det även när MESHY_CLI_NO_BROWSER är satt. För att välja det själv, kör meshy auth login --device.

meshy auth login --device

API-nycklar och CI

För CI och andra obemannade jobb, använd en API-nyckel istället för en webbläsarinloggning. Ange den i miljövariabeln MESHY_API_KEY. Den har prioritet över en sparad inloggning.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Du kan även spara en nyckel med meshy auth login --with-key msy_YOUR_API_KEY.

CLI:n använder den första autentiseringsuppgift den hittar, i denna ordning: --api-key, MESHY_API_KEY, --api-key-file, och sedan den sparade inloggningen. Om CLI:n använder ett annat konto än du förväntar dig, kör meshy auth status för att se vilken autentiseringsuppgift som gäller.

Kinasidan

Ett Meshy-konto fungerar på båda sidorna. För att använda meshy.cn, logga in med meshy auth login --region cn. CLI:n sparar regionen tillsammans med din inloggning, så att senare kommandon anropar api.meshy.cn utan flagga. För att byta tillbaka, logga in med --region global.

Skapa din första modell

meshy make kör hela flödet i ett enda kommando. En textprompt kör en Text till 3D-förhandsgranskning och sedan en refine. En bild kör en enda texturerad Bild till 3D-uppgift.

Kontrollera först vad en körning kommer att göra och hur många credits den kommer att kosta, utan att spendera några:

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

Kör den sedan och spara modellen till en mapp med -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

Mappen innehåller nu modellen, dess miniatyr och en meta.json-fil. För att istället starta från ett foto, ange dess sökväg eller URL: meshy make ./cat.png -o out/cat/.

Commands

De flesta API-endpoints är egna kommandon, och varje task-kommando tar samma verb: create, get, list, wait, stream och delete. För en endpoint utan eget kommando, använd meshy api.

Dessa kommandon täcker de vanliga uppgifterna:

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

För ett kommandos flaggor, kör meshy <resource> --help. För varje endpoints parametrar och kreditkostnader, se dess sida i dessa dokument, till exempel Text till 3D.

CLI:n har också lokala hjälpmedel för 3D-utskrift, såsom meshy inspect faces, meshy mesh prepare-print och meshy slicer. De körs på din dator och anropar inte API:et. Se Using meshy-cli för alla kommandon.

Scripts, agent och CI

JSON-utdata

När dess utdata går till ett rör, en fil, ett skript eller en AI-agent skriver CLI:n ut JSON. I en terminal visar den en läsbar vy. Skicka med --format json (eller --json) för att alltid få JSON.

Varje kommando skriver ut exakt ett JSON-dokument till stdout, med samma sex nycklar. Progress och meddelanden skickas till 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 anger om CLI-kommandot fungerade. Uppgiftens eget tillstånd finns i result.task.status. Till exempel returnerar get på en misslyckad uppgift ok: true, eftersom själva anropet fungerade.

CLI:n skickar varje create-begäran en gång och försöker aldrig på egen hand igen, så ett nätverksfel kan inte skapa, och debitera för, en andra uppgift.

Avslutningskoder

Avslutningskoden talar om för ett skript vad som hände:

För koderna 11 till 14 samt det fullständiga utdataformatet, se Skript och agenter.

GitHub Actions

Lagra din API-nyckel som en repository-hemlighet (repository secret) med namnet MESHY_API_KEY, kör sedan CLI:n i ett jobb:

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/

Steget misslyckas när CLI:n avslutas med en kod som inte är noll.

AI-agenter

Alla agenter som kan köra skalkommandon kan använda CLI:t, inklusive Claude Code, Cursor och Codex. Agenten får JSON automatiskt.

För att lära din agent Meshy-arbetsflödena, installera det öppna källkodspaketet meshy-3d-agent. Det körs via CLI:t.

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

Referens

Globala flaggor

Dessa flaggor fungerar på alla kommandon:

Miljövariabler

CLI:t läser dessa variabler:

Var autentiseringsuppgifter lagras

CLI:t lagrar autentiseringsuppgifter i ~/.config/meshy/credentials.v2.json, som endast är läsbar av dig. Autentiseringsuppgiften i den är krypterad med en nyckel som förvaras i operativsystemets nyckelring: Keychain på macOS, DPAPI på Windows, eller Secret Service på Linux. Där ingen nyckelring är tillgänglig, exempelvis i en container eller via SSH, är nyckeln en fil bredvid autentiseringsuppgifterna.

Uppdateringar och avinstallation

CLI:t kontrollerar npm efter en ny version högst en gång per dag och meddelar dig via stderr. Det ändrar aldrig din stdout. Varje API-förfrågan har en User-Agent-header med CLI-versionen, ditt operativsystem och den AI-agent som kör CLI:t, om en sådan upptäcks. För att utesluta agenten, ange MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

För att se vad som ändrats i varje version, se releases på GitHub.

Felsökning

Kör meshy doctor först. Det kontrollerar din konfiguration utan att anropa API:et. Här är de vanligaste problemen:

För att rapportera ett fel, öppna ett ärende i meshy-cli-repot.

Nästa steg

• Se varje endpoints parametrar och kostnader i API-referensen.
• Jämför CLI:t med MCP server i AI-integration.
• Läs Using meshy-cli för alla kommandon och flaggor.