Meshy CLI

Generuj, śledź i pobieraj modele Meshy bezpośrednio z terminala. Jedno polecenie zamienia prompt lub obraz w teksturowany model, a większość punktów końcowych API jest dostępna jako osobne polecenia.

Meshy CLI (meshy) korzysta z tego samego REST API co reszta tej dokumentacji, w tych samych cenach. Logujesz się raz w przeglądarce, więc nie potrzebujesz klucza API. W terminalu wyświetla czytelny widok, a w skrypcie, potoku, CI lub agencie AI zwraca dane w formacie JSON.

Instalacja

CLI wymaga Node.js w wersji 22.12 lub nowszej. Działa na macOS, Linuksie i Windowsie.

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

Pakiet instaluje dwa polecenia, meshy i meshy-cli. Ta sama kompilacja jest również publikowana jako @meshy-ai/cli. Zainstaluj tylko jeden z tych dwóch pakietów, ponieważ oba udostępniają polecenie meshy, a npm odmówi instalacji drugiego z błędem EEXIST.

CLI jest open source. Jego kod źródłowy znajduje się w repozytorium meshy-cli na GitHubie.

Sign in

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

meshy auth login otwiera stronę logowania Meshy w przeglądarce i zapisuje poświadczenia na Twoim komputerze. Jeśli przeglądarka się nie otworzy, skopiuj adres URL wyświetlony przez CLI.

Zdalne maszyny, SSH i kontenery

Na maszynie bez przeglądarki meshy auth login wyświetla zamiast tego link i krótki kod. Otwórz link na dowolnym urządzeniu, na przykład na laptopie lub telefonie, zaloguj się i wpisz kod. CLI samodzielnie zakończy logowanie.

CLI wybiera ten tryb, gdy wykryje SSH, kontener, CI, system Linux bez wyświetlacza lub brak interaktywnego terminala, na przykład gdy polecenie uruchamia agent AI. Wybiera go również wtedy, gdy ustawiona jest zmienna MESHY_CLI_NO_BROWSER. Aby wybrać ten tryb samodzielnie, uruchom meshy auth login --device.

meshy auth login --device

Klucze API i CI

W przypadku CI i innych automatycznych zadań użyj klucza API zamiast logowania przez przeglądarkę. Ustaw go w zmiennej środowiskowej MESHY_API_KEY. Ma ona priorytet nad zapisanym logowaniem.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Możesz również zapisać klucz za pomocą meshy auth login --with-key msy_YOUR_API_KEY.

CLI używa pierwszych znalezionych danych uwierzytelniających, w następującej kolejności: --api-key, MESHY_API_KEY, --api-key-file, a następnie zapisane logowanie. Jeśli CLI używa innego konta niż oczekujesz, uruchom meshy auth status, aby sprawdzić, które dane uwierzytelniające są aktualnie używane.

Serwis chiński

Jedno konto Meshy działa w obu serwisach. Aby korzystać z meshy.cn, zaloguj się za pomocą meshy auth login --region cn. CLI zapisuje region razem z Twoim logowaniem, dzięki czemu kolejne polecenia wywołują api.meshy.cn bez dodatkowej flagi. Aby wrócić do poprzedniego ustawienia, zaloguj się z --region global.

Stwórz swój pierwszy model

meshy make uruchamia cały proces za pomocą jednego polecenia. Prompt tekstowy uruchamia podgląd Tekst na 3D, a następnie refine. Obraz uruchamia jedno zadanie Obraz na 3D z teksturami.

Najpierw sprawdź, co zrobi dane uruchomienie i ile będzie kosztować w kredytach, bez wydawania żadnych:

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

Następnie uruchom je i zapisz model w folderze za 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

Folder zawiera teraz model, jego miniaturę oraz plik meta.json. Aby zamiast tego zacząć od zdjęcia, podaj jego ścieżkę lub adres URL: meshy make ./cat.png -o out/cat/.

Komendy

Większość punktów końcowych API to samodzielne komendy, a każda komenda zadania przyjmuje te same czasowniki: create, get, list, wait, stream oraz delete. Dla punktu końcowego bez własnej komendy, użyj meshy api.

Te komendy obejmują typowe zadania:

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

Aby poznać flagi danej komendy, uruchom meshy <resource> --help. Aby zapoznać się z parametrami i kosztami w kredytach dla każdego punktu końcowego, zobacz jego stronę w tej dokumentacji, taką jak Tekst na 3D.

CLI posiada również lokalne narzędzia pomocnicze do druku 3D, takie jak meshy inspect faces, meshy mesh prepare-print oraz meshy slicer. Działają one na Twoim komputerze i nie wywołują API. Zobacz Using meshy-cli, aby poznać wszystkie komendy.

Skrypty, agenci i CI

Wyjście JSON

Gdy dane wyjściowe trafiają do potoku, pliku, skryptu lub agenta AI, CLI wypisuje JSON. W terminalu wyświetla czytelny widok. Przekaż --format json (lub --json), aby zawsze otrzymywać JSON.

Każde polecenie wypisuje dokładnie jeden dokument JSON na stdout, z tymi samymi sześcioma kluczami. Postęp i komunikaty trafiają na 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 mówi, czy polecenie CLI się powiodło. Stan samego zadania znajduje się w result.task.status. Na przykład get dla nieudanego zadania zwraca ok: true, ponieważ samo żądanie zadziałało poprawnie.

CLI wysyła każde żądanie create jednokrotnie i nigdy nie ponawia go samodzielnie, dzięki czemu błąd sieci nie może utworzyć ani naliczyć opłaty za drugie zadanie.

Kody wyjścia

Kod wyjścia informuje skrypt o tym, co się wydarzyło:

Informacje o kodach od 11 do 14 oraz pełnym formacie danych wyjściowych znajdziesz w Scripts and agents.

GitHub Actions

Zapisz swój klucz API jako sekret repozytorium o nazwie MESHY_API_KEY, a następnie uruchom CLI w ramach zadania:

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 kończy się niepowodzeniem, gdy CLI zakończy działanie z kodem innym niż zero.

Agenci AI

Każdy agent, który potrafi uruchamiać polecenia powłoki, może korzystać z CLI, w tym Claude Code, Cursor i Codex. Agent otrzymuje JSON automatycznie.

Aby nauczyć swojego agenta przepływów pracy Meshy, zainstaluj open-source'owy pakiet umiejętności meshy-3d-agent. Działa on w CLI.

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

Dokumentacja

Flagi globalne

Te flagi działają w przypadku każdego polecenia:

Zmienne środowiskowe

CLI odczytuje następujące zmienne:

Gdzie przechowywane są dane uwierzytelniające

CLI przechowuje dane uwierzytelniające w pliku ~/.config/meshy/credentials.v2.json, odczytywalnym wyłącznie przez Ciebie. Zawarte w nim dane uwierzytelniające są zaszyfrowane kluczem przechowywanym w systemowym brelok: Keychain na macOS, DPAPI na Windows lub Secret Service na Linuksie. Tam, gdzie brelok jest niedostępny, na przykład w kontenerze lub przez SSH, kluczem jest plik znajdujący się obok danych uwierzytelniających.

Aktualizacje i odinstalowanie

CLI sprawdza w npm dostępność nowej wersji co najwyżej raz dziennie i informuje o tym na stderr. Nigdy nie zmienia Twojego stdout. Każde żądanie API zawiera nagłówek User-Agent z wersją CLI, Twoim systemem operacyjnym oraz agentem AI uruchamiającym CLI, jeśli taki zostanie wykryty. Aby pominąć informację o agencie, ustaw MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

Aby zobaczyć, co zmieniło się w poszczególnych wersjach, zajrzyj do releases na GitHubie.

Rozwiązywanie problemów

Najpierw uruchom meshy doctor. Sprawdza on Twoją konfigurację bez wywoływania API. Oto najczęstsze problemy:

Aby zgłosić błąd, otwórz zgłoszenie w repozytorium meshy-cli.

Kolejne kroki

• Sprawdź parametry i koszty każdego punktu końcowego w dokumentacji API.
• Porównaj CLI z MCP server w sekcji Integracja z AI.
• Przeczytaj Using meshy-cli, aby poznać wszystkie polecenia i flagi.