Meshy CLI

Generujte, sledujte a stahujte modely Meshy přímo z terminálu. Jeden příkaz promění prompt nebo obrázek v model s texturou a většina API endpointů má podobu samostatných příkazů.

Meshy CLI (meshy) volá stejné REST API jako zbytek této dokumentace, za stejné ceny. Přihlásíte se jednou ve svém prohlížeči, takže nepotřebujete API klíč. V terminálu zobrazuje přehledný výstup, a ve skriptu, rouře (pipe), CI nebo AI agentovi vypisuje JSON.

Instalace

CLI vyžaduje Node.js 22.12 nebo novější. Běží na macOS, Linuxu a Windows.

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

Balíček nainstaluje dva příkazy, meshy a meshy-cli. Stejná sestava je také publikována jako @meshy-ai/cli. Nainstalujte pouze jeden z těchto dvou balíčků, protože oba poskytují příkaz meshy a npm odmítne instalaci druhého z nich s chybou EEXIST.

CLI je open source. Jeho zdrojový kód najdete v repozitáři meshy-cli na GitHubu.

Přihlášení

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

meshy auth login otevře ve vašem prohlížeči přihlašovací stránku Meshy a uloží přihlašovací údaje do vašeho počítače. Pokud se prohlížeč neotevře, zkopírujte adresu URL, kterou CLI vypíše.

Vzdálené stroje, SSH a kontejnery

Na stroji bez prohlížeče meshy auth login místo toho vypíše odkaz a krátký kód. Otevřete odkaz na libovolném zařízení, například na notebooku nebo telefonu, přihlaste se a zadejte kód. CLI přihlášení dokončí samo.

CLI tento postup zvolí, pokud detekuje SSH, kontejner, CI, Linux bez displeje nebo neinteraktivní terminál, například když příkaz spouští AI agent. Zvolí jej také v případě, že je nastavena proměnná MESHY_CLI_NO_BROWSER. Chcete-li jej zvolit sami, spusťte meshy auth login --device.

meshy auth login --device

API klíče a CI

Pro CI a další automatizované úlohy použijte API klíč místo přihlášení přes prohlížeč. Nastavte jej do proměnné prostředí MESHY_API_KEY. Má prioritu před uloženým přihlášením.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Klíč lze také uložit pomocí meshy auth login --with-key msy_YOUR_API_KEY.

CLI použije první přihlašovací údaj, který najde, v tomto pořadí: --api-key, MESHY_API_KEY, --api-key-file, poté uložené přihlášení. Pokud CLI používá jiný účet, než očekáváte, spusťte meshy auth status, abyste zjistili, který přihlašovací údaj je aktuálně použit.

China site

Jeden účet Meshy funguje na obou webech. Pro použití meshy.cn se přihlaste pomocí meshy auth login --region cn. CLI uloží region spolu s vaším přihlášením, takže pozdější příkazy volají api.meshy.cn bez nutnosti uvádět příznak. Pro přepnutí zpět se přihlaste pomocí --region global.

Vytvořte svůj první model

meshy make spustí celý postup jediným příkazem. Textový prompt spustí náhled Text na 3D a následně refine. Obrázek spustí jednu texturovanou úlohu Obrázek na 3D.

Nejprve zkontrolujte, co daný běh udělá a kolik bude stát kreditů, aniž byste jakékoli utratili:

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

Poté jej spusťte a uložte model do složky pomocí -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

Složka nyní obsahuje model, jeho miniaturu a soubor meta.json. Pokud chcete začít z fotografie místo toho, předejte její cestu nebo URL: meshy make ./cat.png -o out/cat/.

Příkazy

Většina API endpointů jsou samy o sobě příkazy a každý příkaz pro úlohu používá stejná slovesa: create, get, list, wait, stream a delete. U endpointu bez vlastního příkazu použijte meshy api.

Tyto příkazy pokrývají běžné úlohy:

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

Přepínače daného příkazu zobrazíte spuštěním meshy <resource> --help. Parametry a náklady na kredity pro jednotlivé endpointy najdete na příslušné stránce této dokumentace, například Text na 3D.

CLI obsahuje také lokální pomocné nástroje pro 3D tisk, například meshy inspect faces, meshy mesh prepare-print a meshy slicer. Ty běží na vašem počítači a nevolají API. Úplný seznam příkazů najdete v Using meshy-cli.

Scripty, agenti a CI

Výstup JSON

Když jde výstup do roury, souboru, skriptu nebo AI agenta, CLI vypisuje JSON. V terminálu vypisuje čitelné zobrazení. Předejte --format json (nebo --json), abyste JSON získali vždy.

Každý příkaz vypíše na stdout přesně jeden dokument JSON se stejnými šesti klíči. Progress a zprávy jdou do 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 udává, zda příkaz CLI proběhl úspěšně. Vlastní stav úlohy je v result.task.status. Například get u neúspěšné úlohy vrátí ok: true, protože samotný požadavek proběhl v pořádku.

CLI odešle každý požadavek na vytvoření jen jednou a sám od sebe jej nikdy neopakuje, takže chyba sítě nemůže vytvořit a zpoplatnit druhou úlohu.

Exit kódy

Exit kód sděluje skriptu, co se stalo:

Kódy 11 až 14 a úplný formát výstupu najdete v Scripts and agents.

GitHub Actions

Uložte svůj API klíč jako repository secret s názvem MESHY_API_KEY, poté spusťte CLI v jobu:

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/

Krok selže, pokud CLI skončí s nenulovým kódem.

AI agenti

Jakýkoli agent, který umí spouštět shellové příkazy, může používat CLI, včetně Claude Code, Cursor a Codex. Agent získá JSON automaticky.

Chcete-li naučit svého agenta pracovní postupy Meshy, nainstalujte open-source sadu dovedností meshy-3d-agent. Běží v rámci CLI.

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

Reference

Globální příznaky

Tyto příznaky fungují u každého příkazu:

Proměnné prostředí

CLI čte tyto proměnné:

Kde jsou uloženy přihlašovací údaje

CLI ukládá přihlašovací údaje do ~/.config/meshy/credentials.v2.json, čitelné pouze vámi. Přihlašovací údaj v něm je zašifrován klíčem uloženým v systémové klíčence: Keychain na macOS, DPAPI na Windows nebo Secret Service na Linuxu. Tam, kde není klíčenka k dispozici, například v kontejneru nebo přes SSH, je klíč uložen v souboru vedle přihlašovacích údajů.

Aktualizace a odinstalace

CLI kontroluje npm kvůli nové verzi nejvýše jednou denně a informuje vás o tom na stderr. Nikdy nemění váš stdout. Každý API požadavek nese hlavičku User-Agent s verzí CLI, vaším operačním systémem a AI agentem, který CLI spouští, pokud nějaký detekuje. Chcete-li agenta vynechat, nastavte MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

Chcete-li zjistit, co se změnilo v jednotlivých verzích, podívejte se na releases na GitHubu.

Řešení problémů

Nejprve spusťte meshy doctor. Zkontroluje vaše nastavení bez volání API. Toto jsou nejčastější problémy:

Chcete-li nahlásit chybu, otevřete issue v repozitáři meshy-cli.

Další kroky

• Parametry a náklady každého koncového bodu najdete v referenční dokumentaci API.
• Porovnejte CLI s MCP serverem v sekci Integrace AI.
• Přečtěte si Using meshy-cli, kde najdete všechny příkazy a přepínače.