Meshy CLI

Gere, acompanhe e baixe modelos do Meshy a partir do seu terminal. Um comando transforma um prompt ou uma imagem em um modelo texturizado, e a maioria dos endpoints da API são comandos próprios.

O Meshy CLI (meshy) chama a mesma API REST do restante desta documentação, pelos mesmos preços. Você faz login uma vez no navegador, então não precisa de uma chave de API. Em um terminal, ele exibe uma visualização legível, e em um script, um pipe, CI ou um agente de IA, ele exibe JSON.

Instalar

A CLI precisa do Node.js 22.12 ou posterior. Ela é executada no macOS, Linux e Windows.

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

O pacote instala dois comandos, meshy e meshy-cli. A mesma build também é publicada como @meshy-ai/cli. Instale apenas um dos dois pacotes, pois ambos fornecem o comando meshy e o npm recusa o segundo com EEXIST.

A CLI é open source. Seu código-fonte está no repositório meshy-cli no GitHub.

Sign in

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

meshy auth login abre uma página de login do Meshy no seu navegador e armazena a credencial no seu computador. Se o navegador não abrir, copie a URL que a CLI exibe.

Máquinas remotas, SSH e contêineres

Em uma máquina sem navegador, meshy auth login exibe um link e um código curto em vez disso. Abra o link em qualquer dispositivo, como seu notebook ou celular, faça login e insira o código. A CLI finaliza o login sozinha.

A CLI escolhe esse fluxo quando detecta SSH, um contêiner, CI, Linux sem um display, ou nenhum terminal interativo, como quando um agente de IA executa o comando. Ela também escolhe esse fluxo quando MESHY_CLI_NO_BROWSER está definido. Para escolher esse fluxo você mesmo, execute meshy auth login --device.

meshy auth login --device

Chaves de API e CI

Para CI e outros trabalhos não supervisionados, use uma chave de API em vez de um login via navegador. Defina-a na variável de ambiente MESHY_API_KEY. Ela tem prioridade sobre um login armazenado.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Você também pode armazenar uma chave com meshy auth login --with-key msy_YOUR_API_KEY.

A CLI usa a primeira credencial que encontrar, nesta ordem: --api-key, MESHY_API_KEY, --api-key-file, depois o login armazenado. Se a CLI usar uma conta diferente da esperada, execute meshy auth status para ver qual credencial está em vigor.

Site China

Uma única conta Meshy funciona em ambos os sites. Para usar meshy.cn, faça login com meshy auth login --region cn. A CLI armazena a região junto com o seu login, então os comandos seguintes chamam api.meshy.cn sem a necessidade de uma flag. Para voltar, faça login com --region global.

Crie seu primeiro modelo

meshy make executa todo o fluxo em um único comando. Um prompt de texto executa uma prévia de Texto para 3D e, em seguida, um refine. Uma imagem executa uma única tarefa de Imagem para 3D texturizada.

Primeiro, verifique o que uma execução vai fazer e quantos créditos ela vai custar, sem gastar nenhum:

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

Em seguida, execute-a e salve o modelo em uma pasta com -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

A pasta agora contém o modelo, sua miniatura e um arquivo meta.json. Para começar a partir de uma foto, basta passar seu caminho ou URL: meshy make ./cat.png -o out/cat/.

Commands

A maioria dos endpoints da API são comandos próprios, e cada comando de tarefa aceita os mesmos verbos: create, get, list, wait, stream e delete. Para um endpoint sem comando próprio, use meshy api.

Estes comandos cobrem as tarefas comuns:

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

Para ver as flags de um comando, execute meshy <resource> --help. Para os parâmetros e custos em créditos de cada endpoint, consulte sua página nesta documentação, como Texto para 3D.

A CLI também possui utilitários locais para impressão 3D, como meshy inspect faces, meshy mesh prepare-print e meshy slicer. Eles rodam no seu computador e não chamam a API. Consulte Using meshy-cli para ver todos os comandos.

Scripts, agents e CI

Saída JSON

Quando a saída é direcionada para um pipe, um arquivo, um script ou um agente de IA, a CLI imprime JSON. Em um terminal, ela imprime uma visualização legível. Passe --format json (ou --json) para sempre obter JSON.

Cada comando imprime exatamente um documento JSON na stdout, com as mesmas seis chaves. Progress e mensagens vão para a 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 indica se o comando da CLI funcionou. O estado da própria tarefa está em result.task.status. Por exemplo, get em uma tarefa com falha retorna ok: true, porque a requisição em si funcionou.

A CLI envia cada requisição de criação uma única vez e nunca a repete por conta própria, de modo que um erro de rede não pode criar, e cobrar por, uma segunda tarefa.

Códigos de saída

O código de saída informa a um script o que aconteceu:

Para os códigos 11 a 14 e o formato de saída completo, consulte Scripts e agentes.

GitHub Actions

Armazene sua chave de API como um segredo do repositório com o nome MESHY_API_KEY e, em seguida, execute a CLI em um 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/

A etapa falha quando a CLI é encerrada com um código diferente de zero.

Agentes de IA

Qualquer agente que consiga executar comandos de shell pode usar a CLI, incluindo Claude Code, Cursor e Codex. O agente recebe JSON automaticamente.

Para ensinar os fluxos de trabalho do Meshy ao seu agente, instale o pacote de skills de código aberto meshy-3d-agent. Ele roda na CLI.

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

Reference

Flags globais

Essas flags funcionam em todos os comandos:

Variáveis de ambiente

A CLI lê estas variáveis:

Onde as credenciais são armazenadas

A CLI armazena as credenciais em ~/.config/meshy/credentials.v2.json, legível somente por você. A credencial nele é criptografada com uma chave mantida no chaveiro do sistema operacional: Keychain no macOS, DPAPI no Windows, ou o Secret Service no Linux. Onde nenhum chaveiro está disponível, como em um contêiner ou via SSH, a chave é um arquivo ao lado das credenciais.

Atualizações e desinstalação

A CLI verifica o npm em busca de uma nova versão no máximo uma vez por dia e avisa você via stderr. Ela nunca altera sua stdout. Cada requisição à API carrega um cabeçalho User-Agent com a versão da CLI, seu sistema operacional e o agente de IA que executa a CLI, caso detecte algum. Para omitir o agente, defina MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

Para ver o que mudou em cada versão, consulte os releases no GitHub.

Troubleshooting

Execute meshy doctor primeiro. Ele verifica sua configuração sem chamar a API. Estes são os problemas comuns:

Para relatar um bug, abra uma issue no repositório meshy-cli.

Próximos passos

• Veja os parâmetros e custos de cada endpoint na referência da API.
• Compare o CLI com o MCP server na Integração de IA.
• Leia Using meshy-cli para conhecer todos os comandos e flags.