Meshy CLI

Genera, rastrea y descarga modelos de Meshy desde tu terminal. Un solo comando convierte un prompt o una imagen en un modelo con textura, y la mayoría de los endpoints de API son comandos propios.

El Meshy CLI (meshy) llama a la misma API REST que el resto de esta documentación, a los mismos precios. Inicias sesión una vez en tu navegador, por lo que no necesitas una clave de API. En una terminal muestra una vista legible, y en un script, una tubería, CI o un agente de IA muestra JSON.

Instalación

La CLI necesita Node.js 22.12 o posterior. Funciona en macOS, Linux y Windows.

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

El paquete instala dos comandos, meshy y meshy-cli. La misma compilación también se publica como @meshy-ai/cli. Instala solo uno de los dos paquetes, ya que ambos proporcionan el comando meshy y npm rechaza el segundo con EEXIST.

La CLI es de código abierto. Su código fuente está en el repositorio meshy-cli en GitHub.

Iniciar sesión

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

meshy auth login abre una página de inicio de sesión de Meshy en tu navegador y almacena la credencial en tu ordenador. Si el navegador no se abre, copia la URL que imprime la CLI.

Máquinas remotas, SSH y contenedores

En una máquina sin navegador, meshy auth login imprime un enlace y un código corto en su lugar. Abre el enlace en cualquier dispositivo, como tu portátil o teléfono, inicia sesión e introduce el código. La CLI finaliza el inicio de sesión por sí sola.

La CLI elige este flujo cuando detecta SSH, un contenedor, CI, Linux sin pantalla, o ningún terminal interactivo, como cuando un agente de IA ejecuta el comando. También lo elige cuando MESHY_CLI_NO_BROWSER está definido. Para elegirlo tú mismo, ejecuta meshy auth login --device.

meshy auth login --device

Claves de API y CI

Para CI y otros trabajos desatendidos, utiliza una clave de API en lugar de un inicio de sesión por navegador. Configúrala en la variable de entorno MESHY_API_KEY. Tiene prioridad sobre un inicio de sesión almacenado.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

También puedes almacenar una clave con meshy auth login --with-key msy_YOUR_API_KEY.

El CLI utiliza la primera credencial que encuentra, en este orden: --api-key, MESHY_API_KEY, --api-key-file, y luego el inicio de sesión almacenado. Si el CLI utiliza una cuenta diferente a la que esperas, ejecuta meshy auth status para ver qué credencial está en vigor.

Sitio de China

Una sola cuenta de Meshy funciona en ambos sitios. Para usar meshy.cn, inicia sesión con meshy auth login --region cn. La CLI guarda la región junto con tu inicio de sesión, de modo que los comandos posteriores llaman a api.meshy.cn sin necesidad de una marca. Para volver al otro sitio, inicia sesión con --region global.

Crea tu primer modelo

meshy make ejecuta todo el flujo en un solo comando. Un prompt de texto ejecuta una vista previa de Texto a 3D y luego un refine. Una imagen ejecuta una única tarea de Imagen a 3D con texturas.

Primero, comprueba qué hará una ejecución y cuántos créditos costará, sin gastar ninguno:

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

Luego ejecútalo y guarda el modelo en una carpeta con -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

La carpeta ahora contiene el modelo, su miniatura y un archivo meta.json. Para partir de una foto en su lugar, pasa su ruta o URL: meshy make ./cat.png -o out/cat/.

Commands

La mayoría de los endpoints de la API son comandos propios, y cada comando de tarea utiliza los mismos verbos: create, get, list, wait, stream y delete. Para un endpoint sin comando propio, usa meshy api.

Estos comandos cubren las tareas comunes:

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 conocer las opciones de un comando, ejecuta meshy <resource> --help. Para conocer los parámetros y costos en créditos de cada endpoint, consulta su página en esta documentación, como Texto a 3D.

El CLI también cuenta con herramientas locales para impresión 3D, como meshy inspect faces, meshy mesh prepare-print y meshy slicer. Estas se ejecutan en tu computadora y no llaman a la API. Consulta Using meshy-cli para ver todos los comandos.

Scripts, agentes y CI

Salida JSON

Cuando su salida se dirige a una tubería, un archivo, un script o un agente de IA, la CLI imprime JSON. En una terminal, imprime una vista legible. Pase --format json (o --json) para obtener siempre JSON.

Cada comando imprime exactamente un documento JSON en stdout, con las mismas seis claves. El progress y los mensajes van 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 si el comando de la CLI funcionó. El propio estado de la tarea está en result.task.status. Por ejemplo, get en una tarea fallida devuelve ok: true, porque la solicitud en sí funcionó.

La CLI envía cada solicitud de creación una sola vez y nunca la reintenta por sí misma, por lo que un error de red no puede crear, ni cobrar, una segunda tarea.

Códigos de salida

El código de salida le indica a un script qué ocurrió:

Para los códigos 11 a 14 y el formato de salida completo, consulta Scripts y agentes.

GitHub Actions

Guarda tu clave de API como un secreto del repositorio llamado MESHY_API_KEY, y luego ejecuta la CLI en un 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/

El paso falla cuando la CLI finaliza con un código distinto de cero.

Agentes de IA

Cualquier agente que pueda ejecutar comandos de shell puede usar la CLI, incluidos Claude Code, Cursor y Codex. El agente obtiene JSON automáticamente.

Para enseñarle a tu agente los flujos de trabajo de Meshy, instala el paquete de habilidades de código abierto meshy-3d-agent. Se ejecuta en la CLI.

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

Referencia

Indicadores globales

Estos indicadores funcionan en todos los comandos:

Variables de entorno

La CLI lee estas variables:

Dónde se almacenan las credenciales

La CLI almacena las credenciales en ~/.config/meshy/credentials.v2.json, legible únicamente por ti. La credencial en él está cifrada con una clave guardada en el llavero del sistema operativo: Keychain en macOS, DPAPI en Windows, o Secret Service en Linux. Cuando no hay ningún llavero disponible, como en un contenedor o por SSH, la clave es un archivo junto a las credenciales.

Actualizaciones y desinstalación

La CLI comprueba en npm si hay una nueva versión como máximo una vez al día y te lo indica por stderr. Nunca modifica tu stdout. Cada solicitud a la API lleva un encabezado User-Agent con la versión de la CLI, tu sistema operativo y el agente de IA que ejecuta la CLI, si detecta alguno. Para omitir el agente, establece 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 qué cambió en cada versión, consulta las releases en GitHub.

Solución de problemas

Ejecuta meshy doctor primero. Comprueba tu configuración sin llamar a la API. Estos son los problemas más comunes:

Para informar de un error, abre un issue en el repositorio meshy-cli.

Próximos pasos

• Consulta los parámetros y costes de cada endpoint en la referencia de la API.
• Compara la CLI con el MCP server en Integración con IA.
• Lee Using meshy-cli para conocer todos los comandos y opciones.