Meshy CLI

Generate, track, and download Meshy models from your terminal. One command turns a prompt or an image into a textured model, and most API endpoints are commands of their own.

The Meshy CLI (meshy) calls the same REST API as the rest of these docs, at the same prices. You sign in once in your browser, so you don't need an API key. In a terminal it prints a readable view, and in a script, a pipe, CI, or an AI agent it prints JSON.

Install

The CLI needs Node.js 22.12 or later. It runs on macOS, Linux, and Windows.

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

The package installs two commands, meshy and meshy-cli. The same build is also published as @meshy-ai/cli. Install only one of the two packages, because both provide the meshy command and npm refuses the second with EEXIST.

The CLI is open source. Its source is in the meshy-cli repository on GitHub.

Sign in

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

meshy auth login opens a Meshy sign-in page in your browser and stores the credential on your computer. If the browser doesn't open, copy the URL that the CLI prints.

Remote machines, SSH and containers

On a machine without a browser, meshy auth login prints a link and a short code instead. Open the link on any device, such as your laptop or phone, sign in, and enter the code. The CLI finishes the sign-in on its own.

The CLI chooses this flow when it detects SSH, a container, CI, Linux without a display, or no interactive terminal, as when an AI agent runs the command. It also chooses it when MESHY_CLI_NO_BROWSER is set. To choose it yourself, run meshy auth login --device.

meshy auth login --device

API keys and CI

For CI and other unattended jobs, use an API key instead of a browser sign-in. Set it in the MESHY_API_KEY environment variable. It takes priority over a stored sign-in.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

You can also store a key with meshy auth login --with-key msy_YOUR_API_KEY.

The CLI uses the first credential it finds, in this order: --api-key, MESHY_API_KEY, --api-key-file, then the stored sign-in. If the CLI uses a different account than you expect, run meshy auth status to see which credential is in effect.

China site

One Meshy account works on both sites. To use meshy.cn, sign in with meshy auth login --region cn. The CLI stores the region with your sign-in, so later commands call api.meshy.cn without a flag. To switch back, sign in with --region global.

Make your first model

meshy make runs the whole flow in one command. A text prompt runs a Text to 3D preview and then a refine. An image runs one textured Image to 3D task.

First, check what a run will do and how many credits it will cost, without spending any:

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

Then run it, and save the model to a folder with -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

The folder now holds the model, its thumbnail, and a meta.json file. To start from a photo instead, pass its path or URL: meshy make ./cat.png -o out/cat/.

Commands

Most API endpoints are commands of their own, and each task command takes the same verbs: create, get, list, wait, stream, and delete. For an endpoint without its own command, use meshy api.

These commands cover the common tasks:

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

For a command's flags, run meshy <resource> --help. For each endpoint's parameters and credit costs, see its page in these docs, such as Text to 3D.

The CLI also has local helpers for 3D printing, such as meshy inspect faces, meshy mesh prepare-print and meshy slicer. They run on your computer and don't call the API. See Using meshy-cli for every command.

Scripts, agents, and CI

JSON output

When its output goes to a pipe, a file, a script or an AI agent, the CLI prints JSON. In a terminal it prints a readable view. Pass --format json (or --json) to always get JSON.

Every command prints exactly one JSON document on stdout, with the same six keys. Progress and messages go to 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 says whether the CLI command worked. The task's own state is in result.task.status. For example, get on a failed task returns ok: true, because the request itself worked.

The CLI sends each create request once and never retries it on its own, so a network error can't create, and charge for, a second task.

Exit codes

The exit code tells a script what happened:

For codes 11 to 14 and the full output format, see Scripts and agents.

GitHub Actions

Store your API key as a repository secret named MESHY_API_KEY, then run the CLI in a 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/

The step fails when the CLI exits with a non-zero code.

AI agents

Any agent that can run shell commands can use the CLI, including Claude Code, Cursor, and Codex. The agent gets JSON automatically.

To teach your agent the Meshy workflows, install the open-source meshy-3d-agent skill pack. It runs on the CLI.

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

Reference

Global flags

These flags work on every command:

Environment variables

The CLI reads these variables:

Where credentials are stored

The CLI stores credentials in ~/.config/meshy/credentials.v2.json, readable only by you. The credential in it is encrypted with a key kept in the OS keychain: Keychain on macOS, DPAPI on Windows, or the Secret Service on Linux. Where no keychain is available, such as in a container or over SSH, the key is a file next to the credentials.

Updates and uninstall

The CLI checks npm for a new version at most once a day and tells you on stderr. It never changes your stdout. Each API request carries a User-Agent header with the CLI version, your OS, and the AI agent running the CLI, if it detects one. To leave out the agent, set MESHY_CLI_AGENT=none.

npm install -g meshy-cli@latest

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

To see what changed in each version, see the releases on GitHub.

Troubleshooting

Run meshy doctor first. It checks your setup without calling the API. These are the common problems:

To report a bug, open an issue in the meshy-cli repository.

Next steps

• See each endpoint's parameters and costs in the API reference.
• Compare the CLI with the MCP server in AI integration.
• Read Using meshy-cli for every command and flag.