meshy-cli

The command line for the Meshy AI API: text-to-3D, image-to-3D, text-to-motion, remesh, convert, resize, UV unwrap, rigging, animation, retexture, 2D images, printability, auto split, multi-color print, Creative Lab products, usage records, plus the local helpers a 3D-printing or agent workflow needs. Built for people and AI agents: a terminal gets a readable view, a pipe or an agent gets JSON.

Install

Requires Node 22.12+. No Python, no other runtime.

npm i -g meshy-cli       # installs `meshy` and `meshy-cli`
meshy doctor             # checks the environment, no network

The same build is published as @meshy-ai/cli. Install one, not both: they share the meshy binary and npm refuses the second with EEXIST (npm uninstall -g @meshy-ai/cli && npm i -g meshy-cli to switch).

Log in

meshy auth login                                # browser sign-in, stored for you
meshy auth login --with-key msy_your_key_here   # or paste an API key
meshy auth status

In CI, set MESHY_API_KEY instead; it wins over a stored login. Get a key at https://www.meshy.ai/developers/keys.

Quick start

One command, one model. make chains the documented flow — a prompt runs text-to-3D preview then refine; an image runs one textured image-to-3D task:

meshy make "a lovely baby husky"
meshy make ./cat.png -o out/cat/                # -o saves model.glb + thumbnail + meta.json
meshy make "a red sports car" --dry-run         # steps and credit estimate, no spend

✓ [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
Took     7m 03s
Credits  ~30 (estimate for the whole chain)
Assets   glb, fbx · textures: base_color, metallic, normal, roughness · thumbnail

tip: download it now:  meshy download --resource text-to-3d --task-id 01a0c94d-… --all --output-dir ./a-lovely-baby-husky

Every Meshy endpoint is also a command of its own, with the same verbs:

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
meshy resources                                            # every command

create / get / list / wait / stream / delete work the same way on every resource; meshy <resource> --help documents each one, and meshy api GET /balance reaches any endpoint the CLI does not model yet.

For scripts and agents

stdout is the result and nothing else; progress and messages go to stderr. Every command prints one meshy.cli/v1 envelope — schema_version, command, ok, result, error, warnings — and piped, redirected or run by an agent the rendering is JSON automatically. Say --format json and the shape never depends on how you are run:

meshy text-to-3d create --mode preview --prompt "a cactus" --async --format json \
  | jq -r .result.submission.task_id

Exit codes are stable (3 auth, 8 timed out, 10 submission unknown, …), and a create is sent exactly once, never retried behind your back. The envelope, the create/wait/stream semantics and the full exit-code table are in docs/scripting.md.

Documentation

• Using meshy-cli — auth in depth, make, every resource, downloads, printing helpers, media inputs, what the terminal shows, global flags, environment variables
• Scripts and agents — the v1 envelope, create / wait / stream guarantees, exit codes, the agent skill
• Developing — building from source, project layout, design notes
• Meshy API reference — parameters and credit costs

License

MIT — see LICENSE.