Meshy CLI

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

A Meshy CLI (meshy) chama a mesma REST API que o resto desta documentação, aos mesmos preços. Inicia sessão uma vez no seu navegador, pelo que não precisa de uma chave de API. Num terminal, apresenta uma vista legível, e num script, numa pipe, em CI ou num agente de IA, apresenta JSON.

Install

O CLI necessita de Node.js 22.12 ou posterior. Funciona em 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. O mesmo build também é publicado como @meshy-ai/cli. Instale apenas um dos dois pacotes, porque ambos fornecem o comando meshy e o npm recusa o segundo com EEXIST.

O CLI é open source. O respetivo código-fonte encontra-se no repositório meshy-cli no GitHub.

Iniciar sessão

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 início de sessão da Meshy no seu navegador e guarda a credencial no seu computador. Se o navegador não abrir, copie o URL que a CLI apresenta.

Máquinas remotas, SSH e contentores

Numa máquina sem navegador, o comando meshy auth login apresenta, em vez disso, uma ligação e um código curto. Abra a ligação em qualquer dispositivo, como o seu portátil ou telemóvel, inicie sessão e introduza o código. A CLI conclui o início de sessão por conta própria.

A CLI escolhe este fluxo quando deteta SSH, um contentor, CI, Linux sem ecrã, ou nenhum terminal interativo, como quando um agente de IA executa o comando. Também o escolhe quando a variável MESHY_CLI_NO_BROWSER está definida. Para o escolher você mesmo, execute meshy auth login --device.

meshy auth login --device

Chaves de API e CI

Para CI e outras tarefas não supervisionadas, utilize uma chave de API em vez de um início de sessão no browser. Defina-a na variável de ambiente MESHY_API_KEY. Esta tem prioridade sobre um início de sessão guardado.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

Também pode guardar uma chave com meshy auth login --with-key msy_YOUR_API_KEY.

A CLI utiliza a primeira credencial que encontrar, pela seguinte ordem: --api-key, MESHY_API_KEY, --api-key-file e, por fim, o início de sessão guardado. Se a CLI utilizar uma conta diferente da esperada, execute meshy auth status para ver qual a credencial em vigor.

China site

Uma única conta Meshy funciona em ambos os sites. Para utilizar o meshy.cn, inicie sessão com meshy auth login --region cn. O CLI guarda a região associada à sua sessão, pelo que os comandos seguintes chamam api.meshy.cn sem necessidade de qualquer flag. Para voltar atrás, inicie sessão com --region global.

Crie o seu primeiro modelo

meshy make executa todo o fluxo num único comando. Um prompt de texto executa uma pré-visualização de Texto para 3D seguida de um refine. Uma imagem executa uma única tarefa de Imagem para 3D com texturas.

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

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

De seguida, execute-a e guarde o modelo numa 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 contém agora o modelo, a respetiva miniatura e um ficheiro meta.json. Para começar a partir de uma fotografia, basta indicar o respetivo 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 conhecer as flags de um comando, execute meshy <resource> --help. Para os parâmetros e custos em créditos de cada endpoint, consulte a respetiva página nesta documentação, como Texto para 3D.

A CLI também tem auxiliares locais para impressão 3D, como meshy inspect faces, meshy mesh prepare-print e meshy slicer. Estes são executados no seu computador e não chamam a API. Consulte Using meshy-cli para ver todos os comandos.

Scripts, agents, and CI

Resultado em JSON

Quando o seu resultado é direcionado para um pipe, um ficheiro, um script ou um agente de IA, a CLI imprime JSON. Num terminal, imprime uma vista legível. Passe --format json (ou --json) para obter sempre JSON.

Cada comando imprime exatamente um documento JSON no stdout, com as mesmas seis chaves. O progress e as mensagens vão para o 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 numa tarefa com FAILED devolve ok: true, porque o próprio pedido funcionou.

A CLI envia cada pedido de criação uma única vez e nunca o repete por sua própria iniciativa, pelo que um erro de rede não pode criar, nem cobrar, uma segunda tarefa.

Códigos de saída

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

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

GitHub Actions

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

O passo falha quando a CLI termina com um código diferente de zero.

Agentes de IA

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

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

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

Referência

Flags globais

Estas flags funcionam em todos os comandos:

Variáveis de ambiente

O CLI lê estas variáveis:

Onde são armazenadas as credenciais

A CLI armazena as credenciais em ~/.config/meshy/credentials.v2.json, legível apenas por si. A credencial nele contida é encriptada com uma chave guardada no porta-chaves do sistema operativo: Keychain no macOS, DPAPI no Windows, ou o Secret Service no Linux. Quando não existe nenhum porta-chaves disponível, como num contentor ou através de SSH, a chave é um ficheiro junto às credenciais.

Atualizações e desinstalação

A CLI verifica no npm se existe uma nova versão, no máximo uma vez por dia, e informa-o através do stderr. Nunca altera o seu stdout. Cada pedido à API transporta um cabeçalho User-Agent com a versão da CLI, o seu sistema operativo, e o agente de IA que está a executar a CLI, caso detete um. 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 as releases no GitHub.

Resolução de problemas

Execute primeiro meshy doctor. Este comando verifica a sua configuração sem chamar a API. Eis os problemas mais comuns:

Para reportar um erro, abra uma issue no repositório meshy-cli.

Passos seguintes

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