{"_id":"@4fu/meshy-cli","_rev":"2-ae3c1979a1e3005e7d766935a22edad6","name":"@4fu/meshy-cli","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@4fu/meshy-cli","version":"0.1.0","keywords":["meshy","3d","cli","ai"],"license":"MIT","_id":"@4fu/meshy-cli@0.1.0","maintainers":[{"name":"4fu","email":"npm@4fwu.com"}],"homepage":"https://github.com/4fuu/meshy-cli#readme","bugs":{"url":"https://github.com/4fuu/meshy-cli/issues"},"bin":{"meshy":"dist/cli.js"},"dist":{"shasum":"3f5a64f6c8b54eb220ce28cd87f661a621277feb","tarball":"https://registry.npmjs.org/@4fu/meshy-cli/-/meshy-cli-0.1.0.tgz","fileCount":44,"integrity":"sha512-gEQECFe0ZQ8Nm5n2h0heubbfFNn2qaCznTe4TxyDtK3LmAiFRJ1CCEUlqErjbIQA9bTrjMrkQAFWBWIiH02G0A==","signatures":[{"sig":"MEQCICR7fdAKnyrP6G5QMjUqwAddAOl2aIw9BJ+Xj9J3Tg0OAiBvRSks+nxIkEKBpl8frGiEXkf78fUEBD9MWVaRWVZ7fw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":147016},"type":"module","engines":{"node":">=20"},"gitHead":"75562b46b5850b3d25e190f4de15aee5fa327407","scripts":{"test":"npm run build && vitest run","build":"tsc -p tsconfig.build.json","check":"npm run format:check && npm run typecheck && npm test","format":"prettier --write .","prepack":"npm run build","typecheck":"tsc --noEmit","coverage:api":"npm run build && node scripts/generate-api-coverage.mjs --check","format:check":"prettier --check .","coverage:api:update":"npm run build && node scripts/generate-api-coverage.mjs"},"_npmUser":{"name":"4fu","email":"npm@4fwu.com"},"repository":{"url":"git+https://github.com/4fuu/meshy-cli.git","type":"git"},"_npmVersion":"11.16.0","description":"Command-line client for the Meshy API","directories":{},"_nodeVersion":"24.18.0","dependencies":{"commander":"^14.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","prettier":"^3.6.2","typescript":"^5.8.3","@types/node":"^24.0.0"},"_npmOperationalInternal":{"tmp":"tmp/meshy-cli_0.1.0_1784640304860_0.7420611916374655","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@4fu/meshy-cli","version":"0.1.1","description":"Command-line client for the Meshy API","license":"MIT","type":"module","bin":{"meshy":"dist/cli.js"},"engines":{"node":">=20"},"scripts":{"build":"tsc -p tsconfig.build.json","check":"npm run format:check && npm run typecheck && npm test","coverage:api":"npm run build && node scripts/generate-api-coverage.mjs --check","coverage:api:update":"npm run build && node scripts/generate-api-coverage.mjs","format":"prettier --write .","format:check":"prettier --check .","prepack":"npm run build","test":"npm run build && vitest run","typecheck":"tsc --noEmit"},"dependencies":{"commander":"^14.0.0"},"devDependencies":{"@types/node":"^24.0.0","prettier":"^3.6.2","typescript":"^5.8.3","vitest":"^3.2.4"},"keywords":["meshy","3d","cli","ai"],"repository":{"type":"git","url":"git+https://github.com/4fuu/meshy-cli.git"},"bugs":{"url":"https://github.com/4fuu/meshy-cli/issues"},"homepage":"https://github.com/4fuu/meshy-cli#readme","publishConfig":{"access":"public"},"_id":"@4fu/meshy-cli@0.1.1","gitHead":"42615317a635b918527524c482170f1e197f1a9d","_nodeVersion":"26.5.1","_npmVersion":"10.9.9","dist":{"integrity":"sha512-xQoBOtGVRsnqJACOZP+5W3O85RZP2cU7TuF2zGdIua/cmJL9ltF/h5oVeMKzpEX8+ljyqGL84Do83EEpSjymLw==","shasum":"c43fdf0ef43b70ba6e4c88f75b4d9c658bf0873e","tarball":"https://registry.npmjs.org/@4fu/meshy-cli/-/meshy-cli-0.1.1.tgz","fileCount":45,"unpackedSize":163776,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD22C+e6fjVW2t8Cp3hqkq345uHGZuyAEuPNie0vOcwPAIgVmgFxSDwKZMSKLG9qYqX4ZuSyTPc8cNZKBj86KYCkAc="}]},"_npmUser":{"name":"4fu","email":"npm@4fwu.com"},"directories":{},"maintainers":[{"name":"4fu","email":"npm@4fwu.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/meshy-cli_0.1.1_1787494185740_0.43394644067476906"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T13:25:04.770Z","modified":"2026-08-23T14:09:46.033Z","0.1.0":"2026-07-21T13:25:05.004Z","0.1.1":"2026-08-23T14:09:45.886Z"},"bugs":{"url":"https://github.com/4fuu/meshy-cli/issues"},"license":"MIT","homepage":"https://github.com/4fuu/meshy-cli#readme","keywords":["meshy","3d","cli","ai"],"repository":{"type":"git","url":"git+https://github.com/4fuu/meshy-cli.git"},"description":"Command-line client for the Meshy API","maintainers":[{"name":"4fu","email":"npm@4fwu.com"}],"readme":"# @4fu/meshy-cli\n\nCommand-line client for the public [Meshy API](https://docs.meshy.ai/en/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.\n\nThe package is release-ready but is not published by this repository setup process.\n\n## Requirements\n\n- Node.js 20 or later\n- A Meshy API key for authenticated commands\n\n## Install\n\n```bash\nnpm install --global @4fu/meshy-cli\nmeshy --version\n```\n\nFor local development:\n\n```bash\nnpm install\nnpm run build\nnode dist/cli.js --help\n```\n\n## Authentication\n\nSave a key through an interactive, masked prompt:\n\n```bash\nmeshy login\n```\n\nThe CLI verifies the key with the non-generating Balance endpoint before saving it. `meshy login --stdin` supports a user-controlled secure pipe.\n\nAlternatively, set `MESHY_API_KEY`. The environment variable takes precedence over saved credentials.\n\n```bash\nexport MESHY_API_KEY=\"msy_...\"\nmeshy --json balance\n```\n\nRemove the saved key with:\n\n```bash\nmeshy logout\n```\n\nThe CLI never prints the key. Do not commit keys or pass them as command arguments.\n\n## Commands\n\nThe following asynchronous resources support `create`, `get`, `delete`, `wait`, `stream`, and `download`. Resources marked with List also support `list`.\n\n| Command                | List | API capability           |\n| :--------------------- | :--: | :----------------------- |\n| `text-to-3d`           | Yes  | Text to 3D v2            |\n| `image-to-3d`          | Yes  | Image to 3D              |\n| `multi-image-to-3d`    | Yes  | Multi-Image to 3D        |\n| `remesh`               | Yes  | Remesh                   |\n| `convert`              | Yes  | Format conversion        |\n| `resize`               | Yes  | Model resizing           |\n| `uv-unwrap`            | Yes  | UV generation            |\n| `rigging`              | Yes  | Auto-rigging             |\n| `animation`            | Yes  | Animation                |\n| `retexture`            | Yes  | Retexturing              |\n| `text-to-image`        | Yes  | Text to Image            |\n| `image-to-image`       | Yes  | Image to Image           |\n| `multi-color-print`    | Yes  | Multi-color 3MF creation |\n| `analyze-printability` | Yes  | Printability analysis    |\n| `repair-printability`  | Yes  | Printability repair      |\n\nAdditional commands:\n\n```bash\nmeshy --json balance\nmeshy --json animation library\nmeshy --json task get <task-id>\nmeshy --json task wait <task-id>\nmeshy --json task stream <task-id>\nmeshy --json task download <task-id>\n```\n\nCreative Lab has `keychain`, `fridge-magnet`, `figure`, `vinyl-figure`, and `lamp` products. Each product exposes `prototype` and `build` stages with all seven asynchronous operations:\n\n```bash\nmeshy --json creative-lab figure prototype create --image-url <url>\nmeshy --json creative-lab figure build create --input-task-id <prototype-id>\nmeshy --json creative-lab figure build wait <build-id>\nmeshy --json creative-lab figure build download <build-id>\n```\n\nRun `meshy <resource> --help` and `meshy <resource> create --help` for the complete command-level options.\n\n## Create Tasks\n\nCreate and return immediately:\n\n```bash\nmeshy --json image-to-3d create --image-url <public-url-or-data-uri>\n```\n\nGenerate a transparent-background reference image:\n\n```bash\nmeshy --json text-to-image create \\\n  --ai-model nano-banana \\\n  --prompt \"a carved wooden desk organizer\" \\\n  --remove-background \\\n  --wait\n```\n\nCreate and poll until completion:\n\n```bash\nmeshy --json text-to-3d create \\\n  --mode preview \\\n  --prompt \"a carved wooden desk organizer\" \\\n  --target-formats glb,obj \\\n  --wait\n```\n\nCreate, wait, and download every output exposed by the task:\n\n```bash\nmeshy --json image-to-3d create \\\n  --image-url <url> \\\n  --wait \\\n  --download \\\n  --output-dir ./asset\n```\n\n`--download` implies waiting. Polling defaults to a 5-second interval and a 1-hour maximum; configure them with `--interval` and `--wait-timeout`.\n\nUse SSE instead of polling:\n\n```bash\nmeshy --json image-to-3d create --image-url <url> --stream\nmeshy --json image-to-3d stream <task-id>\n```\n\nDo not combine `--wait` and `--stream`.\n\nText to 3D uses Meshy's two-stage workflow on one endpoint:\n\n```bash\nmeshy --json text-to-3d create --mode preview --prompt \"a monster mask\" --wait\nmeshy --json text-to-3d create --mode refine --preview-task-id <preview-id> --enable-pbr --wait\n```\n\n## Complete Parameter Coverage\n\nCommon parameters have dedicated flags. Every endpoint-specific parameter, including nested Creative Lab options, can be supplied through JSON:\n\n```bash\nmeshy --json <resource> create --data '{\"field\":\"value\"}'\nmeshy --json <resource> create --file request.json\nmeshy --json <resource> create --stdin\n```\n\nUse only one of `--data`, `--file`, or `--stdin`. Dedicated options and repeatable `--set key=value` entries override structured input fields:\n\n```bash\nmeshy --json creative-lab lamp build create \\\n  --file lamp-build.json \\\n  --input-task-id <prototype-id> \\\n  --set options.base_thickness=2.5 \\\n  --set 'output.formats=[\"glb\",\"obj\"]'\n```\n\n`--set` parses JSON values and supports dotted object paths. Use the current Meshy endpoint documentation rather than guessing unfamiliar parameters.\n\n## Structured Output\n\nWith `--json`, normal commands write exactly one JSON value to stdout. Logs, polling progress, warnings, and errors go to stderr.\n\nSSE commands write JSON Lines to stdout because each event is independently useful:\n\n```jsonl\n{\"id\":\"...\",\"status\":\"IN_PROGRESS\",\"progress\":42}\n{\"id\":\"...\",\"status\":\"SUCCEEDED\",\"progress\":100}\n```\n\nParse 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.\n\n## Continue Existing Tasks\n\nCreated task IDs and their resource paths are recorded locally, allowing later continuation with only the ID:\n\n```bash\nmeshy --json task get <task-id>\nmeshy --json task wait <task-id>\nmeshy --json task download <task-id>\n```\n\nFor a task created elsewhere, provide its resource explicitly:\n\n```bash\nmeshy --json task wait <task-id> --resource image-to-3d\nmeshy --json task wait <task-id> --resource creative-lab/figure/build\n```\n\nTask IDs do not encode their endpoint, so the CLI does not probe or guess.\n\n## Downloads\n\nDownloads 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.\n\n```bash\nmeshy --json task download <task-id> --output-dir ./asset\nmeshy --json task download <task-id> --asset model_urls.glb --asset texture_urls.0.base_color\n```\n\nThe 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.\n\n## Configuration Directory\n\nRuntime state lives under `~/.meshy-cli/`:\n\n```text\n~/.meshy-cli/\n├── credentials.json\n├── tasks.json\n└── downloads/\n    └── <task-id>/\n```\n\n`MESHY_CLI_HOME` can override this location for isolated automation and tests. The directory contains credentials and must not be committed or shared.\n\n## Agent Skill\n\nInstall the repository's `meshy-cli` Skill with [`skills`](https://github.com/vercel-labs/skills):\n\n```bash\nnpx skills add https://github.com/4fuu/meshy-cli\n```\n\nThe 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`](skills/meshy-cli/).\n\n## API Coverage\n\n[`docs/api-coverage.md`](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:\n\n- 15 standard asynchronous resource groups\n- 7 Creative Lab products with 2 independently versioned stages each\n- Balance\n- The public Animation Library\n- Creation, retrieval, listing where supported, deletion, polling, SSE, and downloads\n\nRefresh and verify the generated table with:\n\n```bash\nnpm run coverage:api:update\nnpm run coverage:api\n```\n\nBefore a release, fetch the current Meshy documentation and audit it against the recorded source hash; documentation may have changed since this snapshot.\n\n## Development\n\n```bash\nnpm install\nnpm run format:check\nnpm run typecheck\nnpm test\nnpm run coverage:api\nnpm run build\n```\n\nTests 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.\n\nInspect the package before release:\n\n```bash\nnpm pack --dry-run\nnpm publish --dry-run\n```\n\n## Publishing\n\nThe package is configured as public because it uses the npm scope `@4fu`:\n\n1. Confirm the npm package name and repository URL are correct.\n2. Fetch the current Meshy docs and repeat the API coverage audit.\n3. Update the version with `npm version <patch|minor|major>` according to the intended release.\n4. Run the full development and package inspection commands above.\n5. Confirm `npm whoami` points to an account authorized for the `@4fu` scope.\n6. Run `npm publish --access public` only when intentionally performing the real release.\n\nNo release command is run automatically.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}