> **Reading as an AI agent?** This is the Markdown version of https://docs.meshy.ai/api/cli. > > - Full docs index: https://docs.meshy.ai/llms.txt > - Single-fetch full content: https://docs.meshy.ai/llms-full.txt > - Tool-calling access via MCP server: https://docs.meshy.ai/api/ai > - Command-line access via the Meshy CLI: https://docs.meshy.ai/api/cli --- # 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. > **Note:** Using a chat app that connects to tools over MCP, such as Claude Desktop? See [AI integration](/api/ai#cli-or-mcp) to choose between the CLI and the MCP server. --- ## Install The CLI needs Node.js 22.12 or later. It runs on macOS, Linux, and Windows. **Install** ```bash 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](https://github.com/meshy-dev/meshy-cli) on GitHub. --- ## Sign in **Sign in** ```bash 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`. **Device code** ```bash meshy auth login --device ``` **Paste the code back** ```bash # Prints a URL; after you sign in, paste the code the page shows meshy auth login --manual ``` **Two steps (agents)** ```bash # Step 1: print the link, the code and a flow_id, then exit meshy auth login --no-wait --format json # Step 2: after the user approves, finish the sign-in meshy auth login --device-flow ``` ### API keys and CI For CI and other unattended jobs, use an [API key](/api/authentication) instead of a browser sign-in. Set it in the `MESHY_API_KEY` environment variable. It takes priority over a stored sign-in. **API key** ```bash 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](https://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: **Dry run** ```bash meshy make "a lovely baby husky" --dry-run ``` Then run it, and save the model to a folder with `-o`: **Make a model** ```bash meshy make "a lovely baby husky" -o out/husky/ ``` **Output** ```text ✓ [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: **Endpoint commands** ```bash 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 -o out/cat/ meshy text-to-3d list meshy download --resource text-to-3d --task-id --list meshy balance ``` | Command | What it does | |---|---| | `meshy make` | Runs a whole prompt-to-model or image-to-model flow | | `meshy ` | Calls one endpoint, such as `meshy remesh create` or `meshy rigging get` | | `meshy download` | Lists or saves the files of a finished task | | `meshy balance` | Shows your credit balance | | `meshy api ` | Calls any endpoint directly, such as `meshy api GET /balance` | | `meshy resources` | Lists every command | | `meshy auth` | `login`, `status`, `list`, `use`, `logout` | | `meshy doctor` | Checks your setup | For a command's flags, run `meshy --help`. For each endpoint's parameters and credit costs, see its page in these docs, such as [Text to 3D](/api/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](https://github.com/meshy-dev/meshy-cli/blob/main/docs/usage.md) 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. **Read the task ID** ```bash meshy text-to-3d create --mode preview --prompt "a cactus" --async --format json \ | jq -r .result.submission.task_id ``` **Output shape** ```json { "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: | Code | Meaning | |---|---| | `0` | Success | | `1` | The task failed or was canceled while waiting, or another error | | `2` | Invalid flags or arguments | | `3` | Authentication failed, or no credential | | `4` | The API rejected the request (`400`, `422`) | | `5` | Not found (`404`) | | `6` | Rate limited (`429`) | | `7` | Network error | | `8` | Timed out while waiting. The task keeps running. | | `9` | Not enough credits (`402`) | | `10` | The create request was sent, but its result is unknown. Check `meshy list` before you retry. | | `130` | Interrupted with Ctrl-C | For codes `11` to `14` and the full output format, see [Scripts and agents](https://github.com/meshy-dev/meshy-cli/blob/main/docs/scripting.md). ### GitHub Actions Store your API key as a repository secret named `MESHY_API_KEY`, then run the CLI in a job: **.github/workflows/meshy.yml** ```yaml 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`](https://github.com/meshy-dev/meshy-3d-agent) skill pack. It runs on the CLI. ```bash npx skills add meshy-dev/meshy-3d-agent ``` --- ## Reference ### Global flags These flags work on every command: | Flag | Description | |---|---| | `--format json\|pretty\|ndjson` | Output format. `--json` is short for `--format json`. | | `-o, --output ` | Save the finished task's files to a folder, or one file to a path such as `car.glb` | | `--all-assets` | With `-o`, also save texture maps and other extra files | | `--workspace ` | Write files only inside this folder | | `--api-key ` | Use this API key | | `--api-key-file ` | Read `MESHY_API_KEY` from a file | | `--no-update-check` | Skip the check for a new version | | `-v, --verbose` | Print debug logs to stderr | ### Environment variables The CLI reads these variables: | Variable | Description | |---|---| | `MESHY_API_KEY` | API key. Takes priority over a stored sign-in. | | `MESHY_REGION` | `global` or `cn`. Default: the region of your sign-in, otherwise `global` | | `MESHY_CLI_NO_BROWSER` | Any value stops the CLI from opening a browser, and `meshy auth login` uses the device code | | `MESHY_CONFIG_DIR` | Where the CLI keeps its files. Default: `~/.config/meshy` | | `MESHY_KEYRING` | `file` keeps the encryption key in a file instead of the OS keychain | | `MESHY_CLI_AGENT` | `none` leaves the AI agent name out of the `User-Agent` header | | `NO_COLOR` | Turns off color | ### 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`. **Update** ```bash npm install -g meshy-cli@latest ``` **Uninstall** ```bash meshy auth logout --all # deletes the stored credentials npm uninstall -g meshy-cli ``` To see what changed in each version, see the [releases](https://github.com/meshy-dev/meshy-cli/releases) on GitHub. --- ## Troubleshooting Run `meshy doctor` first. It checks your setup without calling the API. These are the common problems: | Problem | Fix | |---|---| | `EEXIST` when you install | You have the other package installed. Run `npm uninstall -g @meshy-ai/cli`, then install `meshy-cli`. | | The browser doesn't open | Copy the URL that `meshy auth login` prints, or use `meshy auth login --device`. | | The CLI uses the wrong account | `MESHY_API_KEY` takes priority over your sign-in. Run `meshy auth status` to see which credential is in effect. | | A locked keychain blocks sign-in | Set `MESHY_KEYRING=file`. | | Exit code `10` after a create | The CLI can't tell if the task was created. Run `meshy list` before you retry, so you don't pay twice. | To report a bug, open an issue in the [meshy-cli repository](https://github.com/meshy-dev/meshy-cli/issues). --- ## Next steps - See each endpoint's parameters and costs in the [API reference](/api). - Compare the CLI with the MCP server in [AI integration](/api/ai#cli-or-mcp). - Read [Using meshy-cli](https://github.com/meshy-dev/meshy-cli/blob/main/docs/usage.md) for every command and flag.