Meshy CLI

Meshy modellerini terminalinizden oluşturun, izleyin ve indirin. Tek bir komut, bir prompt'u veya bir görseli dokulandırılmış bir modele dönüştürür ve çoğu API uç noktası kendi başına birer komuttur.

Meshy CLI (meshy), bu belgelerin geri kalanıyla aynı REST API'yi, aynı fiyatlarla çağırır. Tarayıcınızda bir kez oturum açarsınız, bu yüzden bir API anahtarına ihtiyacınız olmaz. Bir terminalde okunabilir bir görünüm yazdırır; bir script, pipe, CI veya bir AI ajanında ise JSON yazdırır.

Kurulum

CLI, Node.js 22.12 veya daha üstünü gerektirir. macOS, Linux ve Windows üzerinde çalışır.

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

Paket, meshy ve meshy-cli olmak üzere iki komut kurar. Aynı derleme @meshy-ai/cli olarak da yayınlanır. İki paketten yalnızca birini kurun, çünkü her ikisi de meshy komutunu sağlar ve npm ikincisini EEXIST hatasıyla reddeder.

CLI açık kaynaklıdır. Kaynak kodu GitHub üzerindeki meshy-cli deposunda yer alır.

Oturum açma

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

meshy auth login, tarayıcınızda bir Meshy oturum açma sayfası açar ve kimlik bilgisini bilgisayarınızda saklar. Tarayıcı açılmazsa, CLI'nin yazdırdığı URL'yi kopyalayın.

Uzak makineler, SSH ve konteynerler

Tarayıcısı olmayan bir makinede, meshy auth login bunun yerine bir bağlantı ve kısa bir kod yazdırır. Bağlantıyı dizüstü bilgisayarınız veya telefonunuz gibi herhangi bir cihazda açın, oturum açın ve kodu girin. CLI, oturum açma işlemini kendi başına tamamlar.

CLI, SSH, bir konteyner, CI, ekranı olmayan Linux veya bir AI aracısının komutu çalıştırması gibi etkileşimli olmayan bir terminal tespit ettiğinde bu akışı seçer. Ayrıca MESHY_CLI_NO_BROWSER ayarlandığında da bunu seçer. Bunu kendiniz seçmek için meshy auth login --device komutunu çalıştırın.

meshy auth login --device

API anahtarları ve CI

CI ve diğer gözetimsiz işler için tarayıcıdan oturum açma yerine bir API anahtarı kullanın. Bunu MESHY_API_KEY ortam değişkeninde ayarlayın. Bu, kayıtlı bir oturum açma bilgisine göre önceliklidir.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Ayrıca meshy auth login --with-key msy_YOUR_API_KEY komutuyla da bir anahtar saklayabilirsiniz.

CLI, bulduğu ilk kimlik bilgisini şu sırayla kullanır: --api-key, MESHY_API_KEY, --api-key-file, ardından kayıtlı oturum açma bilgisi. CLI'nin beklediğinizden farklı bir hesap kullandığını fark ederseniz, hangi kimlik bilgisinin etkin olduğunu görmek için meshy auth status komutunu çalıştırın.

Çin sitesi

Tek bir Meshy hesabı her iki sitede de çalışır. meshy.cn sitesini kullanmak için meshy auth login --region cn komutuyla oturum açın. CLI, bölgeyi oturum açma bilginizle birlikte saklar, bu sayede sonraki komutlar bayrak belirtmeden api.meshy.cn adresini çağırır. Geri dönmek için --region global ile oturum açın.

İlk modelinizi oluşturun

meshy make, tüm akışı tek bir komutla çalıştırır. Bir metin prompt'u, bir Metinden 3D'ye preview ardından bir refine çalıştırır. Bir görsel ise tek bir dokulu Görselden 3D'ye görevi çalıştırır.

Öncelikle, herhangi bir kredi harcamadan bir çalıştırmanın ne yapacağını ve kaç kredi tutacağını kontrol edin:

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

Ardından çalıştırın ve modeli -o ile bir klasöre kaydedin:

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

Klasör artık modeli, küçük resmini ve bir meta.json dosyasını içeriyor. Bunun yerine bir fotoğraftan başlamak için yolunu veya URL'sini verin: meshy make ./cat.png -o out/cat/.

Komutlar

API uç noktalarının çoğu kendi başına birer komuttur ve her görev komutu aynı fiilleri alır: create, get, list, wait, stream ve delete. Kendi komutu olmayan bir uç nokta için meshy api kullanın.

Bu komutlar yaygın görevleri kapsar:

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

Bir komutun bayrakları (flags) için meshy <resource> --help komutunu çalıştırın. Her uç noktanın parametreleri ve credit maliyetleri için bu dokümanlardaki ilgili sayfaya bakın, örneğin Metinden 3D'ye.

CLI ayrıca 3D baskı için meshy inspect faces, meshy mesh prepare-print ve meshy slicer gibi yerel yardımcı araçlara da sahiptir. Bunlar bilgisayarınızda çalışır ve API'yi çağırmaz. Tüm komutlar için meshy-cli kullanımı sayfasına bakın.

Scriptler, ajanlar ve CI

JSON çıktısı

Çıktısı bir pipe'a, bir dosyaya, bir script'e veya bir AI ajanına gittiğinde CLI, JSON yazdırır. Bir terminalde ise okunabilir bir görünüm yazdırır. Her zaman JSON almak için --format json (veya --json) geçirin.

Her komut, stdout'ta aynı altı anahtara sahip tam olarak bir JSON belgesi yazdırır. Progress ve mesajlar stderr'e gider.

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, CLI komutunun çalışıp çalışmadığını belirtir. Görevin kendi durumu result.task.status içindedir. Örneğin, başarısız olmuş bir görev üzerinde get çalıştırmak ok: true döndürür, çünkü isteğin kendisi başarıyla çalışmıştır.

CLI, her oluşturma isteğini yalnızca bir kez gönderir ve bunu kendi başına asla yeniden denemez, böylece bir ağ hatası ikinci bir görev oluşturup bunun için ücretlendirme yapılmasına neden olamaz.

Çıkış kodları

Çıkış kodu, bir betiğe ne olduğunu bildirir:

11 ile 14 arasındaki kodlar ve tam çıktı formatı için bkz. Scripts and agents.

GitHub Actions

API anahtarınızı MESHY_API_KEY adlı bir depo gizli anahtarı (repository secret) olarak saklayın, ardından CLI'yi bir iş (job) içinde çalıştırın:

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/

CLI sıfır olmayan bir kodla çıkış yaptığında bu adım başarısız olur.

Yapay zeka ajanları

Kabuk komutları çalıştırabilen her ajan, Claude Code, Cursor ve Codex dahil, CLI'yi kullanabilir. Ajan JSON çıktısını otomatik olarak alır.

Ajanınıza Meshy iş akışlarını öğretmek için açık kaynaklı meshy-3d-agent beceri paketini yükleyin. Bu paket CLI üzerinde çalışır.

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

Referans

Genel bayraklar

Bu bayraklar her komutta çalışır:

Ortam değişkenleri

CLI şu değişkenleri okur:

Kimlik bilgilerinin saklandığı yer

CLI, kimlik bilgilerini yalnızca sizin tarafınızdan okunabilen ~/.config/meshy/credentials.v2.json dosyasında saklar. İçindeki kimlik bilgisi, işletim sistemi anahtarlığında tutulan bir anahtarla şifrelenir: macOS'ta Keychain, Windows'ta DPAPI veya Linux'ta Secret Service. Bir konteyner içinde veya SSH üzerinden olduğu gibi anahtarlığın bulunmadığı durumlarda, anahtar kimlik bilgilerinin yanında bir dosya olarak tutulur.

Güncellemeler ve kaldırma

CLI, npm'de yeni bir sürüm olup olmadığını günde en fazla bir kez kontrol eder ve bunu stderr üzerinden size bildirir. stdout çıktınızı asla değiştirmez. Her API isteği, CLI sürümünü, işletim sisteminizi ve CLI'yi çalıştıran yapay zeka aracısını (algılarsa) içeren bir User-Agent başlığı taşır. Aracıyı hariç tutmak için MESHY_CLI_AGENT=none ayarlayın.

npm install -g meshy-cli@latest

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

Her sürümde nelerin değiştiğini görmek için GitHub'daki releases sayfasına bakın.

Sorun giderme

Önce meshy doctor komutunu çalıştırın. Bu komut, API'yi çağırmadan kurulumunuzu kontrol eder. İşte yaygın sorunlar:

Bir hata bildirmek için meshy-cli deposunda bir konu (issue) açın.

Sonraki adımlar

• Her bir uç noktanın parametrelerini ve maliyetlerini API referansında inceleyin.
• CLI'yi MCP server ile AI entegrasyonu bölümünde karşılaştırın.
• Tüm komutlar ve bayraklar için Using meshy-cli belgesini okuyun.