meshy-dev/meshy-3d-agent / skills/meshy-3d-generation
meshy-3d-generation
VerifiedGenerates and edits digital 3D assets with the Meshy CLI: text-to-3D and image-to-3D models, texturing, remeshing and LODs, UV unwrapping, format conversion (GLB, FBX, OBJ, USDZ, STL, 3MF, Blender), rigging, animation, motion clips from text and reference images. Use when the user asks to make, texture, rig, animate or convert a 3D model or game asset. For physical 3D printing use meshy-3d-printing.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/animation.md | markdown | 4.3 KB |
| references/delivery.md | markdown | 9.2 KB |
| references/pipelines.md | markdown | 20.6 KB |
| references/setup.md | markdown | 13.9 KB |
| references/troubleshooting.md | markdown | 9.6 KB |
| references/visual-hosts.md | markdown | 1.7 KB |
references/setup.md
View on GitHub# Runner, login and output locations
Shared by the generation and print workflows. Three things are settled before any job
starts: **how to run the CLI**, **whether a session already exists**, and **where files go**.
The supported CLI is **0.8.x, from 0.8.6,** on **Node.js 22.12 or newer**.
Contents: 1 runner · 2 reuse a session · 3 first login · 4 where files go · 5 one session
everywhere · 6 API keys · 7 the China site.
## 1. Resolve the runner
In DeepSeek Harness with the Meshy plugin the plugin ships the CLI and holds the sign-in. Check
for it first:
```bash
test -n "$DSH_MESHY_CLI" && echo meshy-dsh
```
When that prints `meshy-dsh`, run every recipe as `"$DSH_MESHY_NODE" "$DSH_MESHY_CLI" …` in
place of `meshy …` (PowerShell: `& $env:DSH_MESHY_NODE $env:DSH_MESHY_CLI …`), keep both paths
quoted, install nothing, and go on to section 2. The shell there cannot store a login, so never
run `auth login`, set `MESHY_CONFIG_DIR` or copy a credential file in it: when `auth status`
reports no usable credential, or a command reports a rejected session, call the
`meshy_sign_in` tool (`region: "cn"` for the China site), show the user its link and code, and
retry once they say they approved; or ask them to sign in from Settings → Meshy. Everywhere
else:
```bash
node --version
meshy --version
```
| Observation | What to do |
|---|---|
| `meshy --version` prints 0.8.6 or a later 0.8.x | run `meshy` |
| no `meshy` command, or a version older than 0.8.6 | install the newest 0.8.x (below), then run `meshy` |
| 0.9 or newer | keep it, since something else may rely on it, and run the temporary package |
| no Node.js, or Node older than 22.12 | stop and report it: the user installs Node.js 22.12+ |
```bash
npm install -g meshy-cli@0.8
```
Check and install without asking first; say in one line that you are installing it. Install at
most once: when `meshy --version` still reports a version older than 0.8.6 afterwards, the
registry this machine uses lags npm, so report that instead of installing again. Never use `sudo`
or change system policy: when the install is refused (permissions, a managed machine, a sandbox), use the temporary package
instead. It runs the same CLI without installing anything: put `npm exec --yes
--package=meshy-cli@0.8.6 --` in front of the same arguments, and the exit code and the JSON on
stdout are forwarded unchanged. Recipes are written as `meshy …`; example:
```bash
npm exec --yes --package=meshy-cli@0.8.6 -- meshy auth status --format json --no-update-check
```
The first such call downloads the package into the npm cache; later calls reuse it. It names an
exact version because `npm exec` keeps reusing whatever matching version it cached first. On Windows
both commands go through `npm.cmd`. A missing `npm` with a working Node.js means the host
stripped npm: report that and ask the user to install the CLI themselves.
## 2. Reuse a working session before logging in
```bash
meshy auth status --format json --no-update-check
```
Every command, auth included, prints one `meshy.cli/v1` envelope on stdout (`ok`, `result`,
`error`, `warnings`). For `auth status` read `result.authenticated`, `result.verified`,
`result.source` and `result.hint` together with the exit code. `ok` only says the command ran:
the unauthenticated and unverified answers below are `ok: true` with exit 3.
- `authenticated: true`, `verified: true`, exit 0: continue with this account. **No new login.**
`result.account` names who is signed in when the site reports it, and may be `null`.
- `authenticated: false`, exit 3: no usable credential; log in (next section).
- `authenticated: true`, `verified: false`, exit 3: a credential exists but verification failed —
which includes network and server errors, not just rejection. Do not start a login or delete
credentials; see [troubleshooting.md](troubleshooting.md).
`auth status --offline` skips the balance and account calls but can still refresh OAuth over the
network.
Use local `doctor` for a diagnostic that must avoid the network entirely.
## 3. First login: one browser approval, then resume the original request
An agent subprocess normally has no TTY, so `auth login` resolves to the device flow on its
own; pass `--device` to make that explicit and deterministic.
```bash
meshy auth login --device --format json --no-update-check
```
In mainland China, or when the user asks for the China site, add `--region cn`
([section 7](#7-the-china-site)): the code is then entered at `meshy.cn`.
The CLI writes the verification instruction to **stderr**, then polls until the user approves or
the code expires:
```text
Enter code WXYZ-1234 at https://www.meshy.ai/device
```
Read that instruction as soon as it appears (ignore preceding npm notices) and show the URL
and user code **verbatim** in a **commentary/progress message, never a final answer**,
as a clickable link plus the code to type. Do not wait for the command to exit first, and do
not summarise the code. Then say what happens next, assuming they have never seen the page:
open the URL, sign in to Meshy if asked, type the code, approve. Nothing is copied back into
the chat — the CLI receives the credential itself.
### Keep the agent turn alive
Run the login as a running tool session and keep waiting on that **same** session in this turn,
with the host's own tool for reading a running command, until it exits. Browser approval ends
the CLI process, not your turn, and a process still running when the turn ends has nobody to
read its result. So do not detach it (`&`, `nohup`, a new terminal), do not end the turn with
"authorize and I will continue", and do not ask the user to reply "done". A tool yield or timeout
is not a code expiry. While it polls, do not start a second login, kill it or poll the API
yourself; send a brief progress note during a long wait. A host whose own skill says it wakes the
session when a background command exits follows that procedure instead.
On approval the CLI prints the envelope with `result.status: "logged_in"` and
`result.verified: true` to stdout and exits 0. Then:
1. Re-run `auth status`; `verified: true` is the proof, not the exit code of `login`.
2. **Continue the request the user originally made**, with the same inputs, output path and
budget they already gave. Logging in is not the deliverable.
Failure branches — each is a different recovery, so read the error rather than retrying blindly:
- **Browser never opened / user is on another device**: the URL and code in the stderr line are
all they need; they can open it anywhere they are signed in to Meshy.
- **Code expired or was denied** (the login exits non-zero after polling, with an error envelope
whose `error.details.oauth_error` names the reason, such as `access_denied` or
`expired_token`): run the *same* login command again for a fresh code. Never re-run a paid
create because a login timed out.
- **`device_flow_not_supported`**: this API host has no device endpoint. Ask the user to run
`meshy auth login` in their own desktop terminal (loopback + browser), or to store their own
key with `meshy auth login --with-key <key>` privately. Never ask for the key in chat.
- **Network blocked by a sandbox** (the login fails within a second with `error.details.code:
"oauth_network"` and a `fetch failed` message, before any URL or code appears): the shell
cannot reach Meshy, so no login can finish there. Run the *same* command again with network
access or outside the sandbox, asking the user to allow it if the host requires approval. Do
not follow the error's `--with-key` hint, probe the network with `curl`, or look for a
credential to reuse (section 5).
- **The host cannot wait in the turn** (no tool reads a running command, or progress messages
reach the user only when the turn ends): use the two-step sign-in below.
### Two-step sign-in
Step one returns at once (add `--region cn` for the China site):
```bash
meshy auth login --device --no-wait --format json --no-update-check
```
It prints `result.verification_url` (the code is already in the link), `result.user_code` and
`result.flow_id`. Keep FLOW_ID in your notes, end the turn with the link and the code, and ask the
user to approve and reply. When they reply:
```bash
meshy auth login --device-flow FLOW_ID --format json --no-update-check
```
It waits while the approval is still pending, saves the session and prints
`result.status: "logged_in"`; verify `auth status` and continue the original request. An expired
or unknown flow means running step one again. A host whose question tool reaches the user can
instead ask with the link and wait for the answer in the same turn, then run step two.
Do not use `--manual` from an agent — it prompts on stdin for a pasted code. Never show a token, a device
code or a signed URL to the user or copy one into chat or a file: task results and sidecars
carry signed URLs, so report paths and task IDs instead of pasting them.
## 4. Where files go
Two paths decide every write. Resolve them from the user's own words *before* the first command:
| The user named | `WORKSPACE` (the write boundary) | `JOB_DIR` (previews, intermediate downloads) | Final model file |
|---|---|---|---|
| nothing | `./meshy_output` | `./meshy_output/<job>` | inside `JOB_DIR` |
| a directory, e.g. `./assets` | `./assets` | `./assets/meshy_output/<job>` | `./assets/<descriptive-name>.<ext>` |
| a file, e.g. `./assets/chest.glb` | `./assets` | `./assets/meshy_output/<job>` | exactly `./assets/chest.glb` |
`<job>` is a short descriptive folder name you choose for this job; the CLI creates it on the first
write, and another job's folder is never reused. `./meshy_output` is only the **default**, never an
override: a path the user asked for wins. When the named directory is itself called
`meshy_output`, `JOB_DIR` is `<that directory>/<job>` (no nested `meshy_output/meshy_output`).
Quote paths with spaces or non-ASCII characters as single shell arguments; they need no other
special handling.
Every command that writes a file (`-o`, `download`, `--save-json`, mesh preparation) carries
`--workspace WORKSPACE`, so the CLI refuses any path that escapes it or follows a symlink out of
it; a `create` or `wait` that saves nothing needs no workspace. Keep one workspace per job:
previews, intermediate downloads and delivered files all live inside it. Say the output location
when the job starts.
Existing files are never silently replaced. `download` refuses to overwrite unless `--overwrite`
is passed, and `-o` refuses a target that holds anything but its own task's earlier output
(rerunning the same `-o` for the same task is fine). So an existing `chest.glb` is a decision — a
new name or, for `download`, an explicit overwrite — covered by what the user already authorized,
not a silent clobber. The sidecar `-o` leaves beside a model is described in
[delivery.md](delivery.md).
## 5. One session, both skills, any directory
The default store is `~/.config/meshy/credentials.v2.json` (mode 0600); the key or tokens in it
are encrypted under a key the OS keeps (Keychain, DPAPI or the Secret Service; a `master.key`
file where none is usable). Generation and printing, in either plugin, reuse it when run as the
same OS user with the same CLI configuration. Changing the working directory does not require
another login. Different users, machines, containers or configuration directories do not
automatically share sessions.
`MESHY_CONFIG_DIR` changes the config directory; `MESHY_CREDENTIALS_PATH` overrides the
credential file. Keep these settings consistent. Only the CLI touches the config directory: never
read, copy, move, edit or delete a file there, never look for credentials anywhere else, and do
not copy tokens between plugins.
`auth list` reports profile kinds with masked credentials. `auth use <name>` changes the shared
active profile, so do not switch it independently in concurrent workflows.
The CLI refreshes stored OAuth tokens near expiry on its own. Where it cannot write the store (a
sandboxed shell) it leaves the login alone instead: a still-valid token keeps working, and an
expired one is exit 3 saying the directory is not writable — run the command outside the sandbox
rather than signing in again inside it.
## 6. Existing API keys remain supported
Credential priority is `--api-key` > `MESHY_API_KEY` > explicit `--api-key-file` > the DeepSeek
Harness plugin's session > stored active profile. An existing environment key overrides browser login; report `source` when
diagnosing account selection, and do not change the user's environment or account implicitly.
In DeepSeek Harness an exported `MESHY_API_KEY` never reaches the CLI (dsh removes
credential-shaped variables); the plugin's sign-in (section 1) or an explicit `--api-key-file` is
used instead.
There is no automatic `.env` discovery. If the user chooses a project key file, pass its
explicit path on authenticated commands. **`auth status` ignores `--api-key-file`**,
so verify that branch with a free balance call instead:
```bash
meshy balance --api-key-file ./.env --format json --no-update-check
```
The CLI reads only the key from that file. Do not source or display it. Never ask for an API
key when browser login is available, and never copy keys or tokens into the conversation,
shell profiles or a new skill-managed file. Share masked status and actionable errors only.
## 7. The China site
One Meshy account works on both sites with the same credits; only the hosts differ. When the user
is in mainland China
or asks for the China site, sign in with `--region cn` instead of the plain device login in
section 3, with the same persistent-session procedure (the code is entered at `meshy.cn`):
```bash
meshy auth login --device --region cn --format json --no-update-check
```
The CLI remembers the region on the profile, so later commands call `api.meshy.cn` on their own;
`--region global` on a new login switches back. For an API-key session set `MESHY_REGION=cn`
instead — it is not credential-shaped, so it survives DeepSeek Harness too. `doctor` shows the
resolved origins. Do not move a user to the China site unasked.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |