@4fu/meshy-cli

Command-line client for the public Meshy API. It provides explicit commands for every API operation documented on 2026-08-23, plus polling, SSE streaming, task continuation, structured output, and output-aware downloads.

The package is release-ready but is not published by this repository setup process.

Requirements

• Node.js 20 or later
• A Meshy API key for authenticated commands

Install

npm install --global @4fu/meshy-cli
meshy --version

For local development:

npm install
npm run build
node dist/cli.js --help

Authentication

Save a key through an interactive, masked prompt:

meshy login

The CLI verifies the key with the non-generating Balance endpoint before saving it. meshy login --stdin supports a user-controlled secure pipe.

Alternatively, set MESHY_API_KEY. The environment variable takes precedence over saved credentials.

export MESHY_API_KEY="msy_..."
meshy --json balance

Remove the saved key with:

meshy logout

The CLI never prints the key. Do not commit keys or pass them as command arguments.

Commands

The following asynchronous resources support create, get, delete, wait, stream, and download. Resources marked with List also support list.

| Command | List | API capability | | :--------------------- | :--: | :----------------------- | | text-to-3d | Yes | Text to 3D v2 | | image-to-3d | Yes | Image to 3D | | multi-image-to-3d | Yes | Multi-Image to 3D | | remesh | Yes | Remesh | | convert | Yes | Format conversion | | resize | Yes | Model resizing | | uv-unwrap | Yes | UV generation | | rigging | Yes | Auto-rigging | | animation | Yes | Animation | | retexture | Yes | Retexturing | | text-to-image | Yes | Text to Image | | image-to-image | Yes | Image to Image | | multi-color-print | Yes | Multi-color 3MF creation | | analyze-printability | Yes | Printability analysis | | repair-printability | Yes | Printability repair |

Additional commands:

meshy --json balance
meshy --json animation library
meshy --json task get <task-id>
meshy --json task wait <task-id>
meshy --json task stream <task-id>
meshy --json task download <task-id>

Creative Lab has keychain, fridge-magnet, figure, vinyl-figure, and lamp products. Each product exposes prototype and build stages with all seven asynchronous operations:

meshy --json creative-lab figure prototype create --image-url <url>
meshy --json creative-lab figure build create --input-task-id <prototype-id>
meshy --json creative-lab figure build wait <build-id>
meshy --json creative-lab figure build download <build-id>

Run meshy <resource> --help and meshy <resource> create --help for the complete command-level options.

Create Tasks

Create and return immediately:

meshy --json image-to-3d create --image-url <public-url-or-data-uri>

Generate a transparent-background reference image:

meshy --json text-to-image create \
  --ai-model nano-banana \
  --prompt "a carved wooden desk organizer" \
  --remove-background \
  --wait

Create and poll until completion:

meshy --json text-to-3d create \
  --mode preview \
  --prompt "a carved wooden desk organizer" \
  --target-formats glb,obj \
  --wait

Create, wait, and download every output exposed by the task:

meshy --json image-to-3d create \
  --image-url <url> \
  --wait \
  --download \
  --output-dir ./asset

--download implies waiting. Polling defaults to a 5-second interval and a 1-hour maximum; configure them with --interval and --wait-timeout.

Use SSE instead of polling:

meshy --json image-to-3d create --image-url <url> --stream
meshy --json image-to-3d stream <task-id>

Do not combine --wait and --stream.

Text to 3D uses Meshy's two-stage workflow on one endpoint:

meshy --json text-to-3d create --mode preview --prompt "a monster mask" --wait
meshy --json text-to-3d create --mode refine --preview-task-id <preview-id> --enable-pbr --wait

Complete Parameter Coverage

Common parameters have dedicated flags. Every endpoint-specific parameter, including nested Creative Lab options, can be supplied through JSON:

meshy --json <resource> create --data '{"field":"value"}'
meshy --json <resource> create --file request.json
meshy --json <resource> create --stdin

Use only one of --data, --file, or --stdin. Dedicated options and repeatable --set key=value entries override structured input fields:

meshy --json creative-lab lamp build create \
  --file lamp-build.json \
  --input-task-id <prototype-id> \
  --set options.base_thickness=2.5 \
  --set 'output.formats=["glb","obj"]'

--set parses JSON values and supports dotted object paths. Use the current Meshy endpoint documentation rather than guessing unfamiliar parameters.

Structured Output

With --json, normal commands write exactly one JSON value to stdout. Logs, polling progress, warnings, and errors go to stderr.

SSE commands write JSON Lines to stdout because each event is independently useful:

{"id":"...","status":"IN_PROGRESS","progress":42}
{"id":"...","status":"SUCCEEDED","progress":100}

Parse SSE output one line at a time. All failures return a nonzero exit code. HTTP errors preserve Meshy's status and response body in stderr; failed tasks preserve task_error details.

Continue Existing Tasks

Created task IDs and their resource paths are recorded locally, allowing later continuation with only the ID:

meshy --json task get <task-id>
meshy --json task wait <task-id>
meshy --json task download <task-id>

For a task created elsewhere, provide its resource explicitly:

meshy --json task wait <task-id> --resource image-to-3d
meshy --json task wait <task-id> --resource creative-lab/figure/build

Task IDs do not encode their endpoint, so the CLI does not probe or guess.

Downloads

Downloads inspect the actual task response and handle model formats, textures, thumbnails, generated images, animation files, print outputs, and Creative Lab outputs without assuming a shared response shape.

meshy --json task download <task-id> --output-dir ./asset
meshy --json task download <task-id> --asset model_urls.glb --asset texture_urls.0.base_color

The JSON result reports each semantic asset name, source URL, and local path. Without --output-dir, output goes under ~/.meshy-cli/downloads/<task-id>/. Existing files are not replaced unless --overwrite is supplied.

Configuration Directory

Runtime state lives under ~/.meshy-cli/:

~/.meshy-cli/
├── credentials.json
├── tasks.json
└── downloads/
    └── <task-id>/

MESHY_CLI_HOME can override this location for isolated automation and tests. The directory contains credentials and must not be committed or shared.

Agent Skill

Install the repository's meshy-cli Skill with skills:

npx skills add https://github.com/4fuu/meshy-cli

The Skill treats Meshy primarily as a 3D asset pipeline. New 3D assets require a generated, reconstruction-ready reference set, a style-consistency review, and explicit approval before a 3D creation call. User-supplied source or style images do not skip this stage unless they are already the explicitly approved reconstruction references. When a reference set must be generated, the agent first asks whether to use an available external image tool; Meshy's image endpoints remain a fallback. The Skill also keeps credentials out of context, preserves task IDs, and uses structured output. Its full command and workflow references are under skills/meshy-cli.

API Coverage

docs/api-coverage.md expands all 148 public HTTP operations documented in Meshy's 2026-08-23 llms-full.txt snapshot and maps each one to a CLI command and test status. It includes:

• 15 standard asynchronous resource groups
• 7 Creative Lab products with 2 independently versioned stages each
• Balance
• The public Animation Library
• Creation, retrieval, listing where supported, deletion, polling, SSE, and downloads

Refresh and verify the generated table with:

npm run coverage:api:update
npm run coverage:api

Before a release, fetch the current Meshy documentation and audit it against the recorded source hash; documentation may have changed since this snapshot.

Development

npm install
npm run format:check
npm run typecheck
npm test
npm run coverage:api
npm run build

Tests use local mock servers and do not consume Meshy credits. The suite covers credentials, API errors, request composition, the complete command registry, polling/SSE primitives, structured CLI output, task persistence, heterogeneous downloads, and Skill structure.

Inspect the package before release:

npm pack --dry-run
npm publish --dry-run

Publishing

The package is configured as public because it uses the npm scope @4fu:

1. Confirm the npm package name and repository URL are correct.
2. Fetch the current Meshy docs and repeat the API coverage audit.
3. Update the version with npm version <patch|minor|major> according to the intended release.
4. Run the full development and package inspection commands above.
5. Confirm npm whoami points to an account authorized for the @4fu scope.
6. Run npm publish --access public only when intentionally performing the real release.

No release command is run automatically.

License

MIT