@meshy-ai/cli 0.4.6 → 0.6.0

package/skills/meshy-cli/SKILL.md

@@ -4,7 +4,7 @@ description: "Generate 3D models, motion clips, 2D images and Creative Lab print
 license: MIT
 compatibility: Requires meshy-cli on PATH (Node 22.12+, no Python) and a stored credential, MESHY_API_KEY or --api-key-file for API commands; network access to api.meshy.ai. Local helpers work offline.
 metadata:
-  version: "1.2.0"
+  version: "1.4.0"
   cli-help: "meshy --help"
 ---
 
@@ -20,14 +20,15 @@ executed; do not use Node's `--env-file`). Never echo the key back or write it
 into a shell profile. `meshy doctor` checks the environment without touching the
 network; `meshy doctor --check-api` makes one free balance call.
 
-## Always ask for the stable envelope
+## Parse the envelope
 
-Add `--output-schema v1 --format json` to every command you parse. Untyped,
-`--format` is `pretty` at a terminal and `json` elsewhere; say both and the
-shape is fixed however you are spawned. `pretty` is a human view that drops
-fields, so never parse it; `json` and `ndjson` carry no colour codes. stdout is then
-exactly one JSON object with six keys — `schema_version, command, ok, result,
-error, warnings` — and nothing else. Progress goes to stderr as plain lines
+Every command prints one `meshy.cli/v1` envelope on stdout. Add `--format json`
+to every command you parse: untyped, `--format` is `pretty` at a terminal and
+`json` elsewhere; say it and the rendering is fixed however you are spawned.
+`pretty` is a human view that drops fields, so never parse it; `json` and
+`ndjson` carry no colour codes. stdout is then exactly one JSON object with six
+keys — `schema_version, command, ok, result, error, warnings` — and nothing
+else. Progress goes to stderr as plain lines
 (none under `ndjson`); it is for people, so read ids from stdout, not from it. `ok` is whether the
 CLI operation completed; `result.task.status` is the server's task state (a `get`
 of a FAILED task is `ok:true`). Fields the server did not send are `null` —
@@ -39,11 +40,11 @@ recoveries) is replaced with a real path.
 ## One model, one command
 
 ```bash
-meshy make "a red sports car" -o car.glb --output-schema v1     # prompt → text-to-3d preview → refine
-meshy make ./cat.png -o out/cat/ --output-schema v1             # image  → image-to-3d, textured
-meshy make "a red sports car" --dry-run --output-schema v1      # planned steps + estimate, no spend, no network
+meshy make "a red sports car" -o car.glb     # prompt → text-to-3d preview → refine
+meshy make ./cat.png -o out/cat/             # image  → image-to-3d, textured
+meshy make "a red sports car" --dry-run      # planned steps + estimate, no spend, no network
 meshy make "..." --max-credits 25                               # refuse to start over budget
-meshy make "..." --async --output-schema v1                     # one POST, returns step 1's task_id + pending_steps
+meshy make "..." --async                     # one POST, returns step 1's task_id + pending_steps
 ```
 
 The input decides the chain and nothing else does. If a later step fails, the
@@ -52,13 +53,13 @@ verbatim rather than starting over, or the finished step is paid for twice.
 
 ## Everything else
 
-`meshy resources --output-schema v1` indexes every command (kind `task`, `query`,
+`meshy resources` indexes every command (kind `task`, `query`,
 `action` or `local`); each task resource carries the same verbs:
 
 ```bash
-meshy <resource> create [flags] [--data '<json>'] [--async] [--timeout <s>] [--operation-id <id>] --output-schema v1
-meshy <resource> get|wait|stream|delete <task-id> --output-schema v1
-meshy <resource> list [--page-size <n>] --output-schema v1
+meshy <resource> create [flags] [--data '<json>'] [--async] [--timeout <s>] [--operation-id <id>]
+meshy <resource> get|wait|stream|delete <task-id>
+meshy <resource> list [--page-size <n>]
 ```
 
 - `create` blocks until the task is terminal; `--async` submits **exactly one
@@ -79,6 +80,13 @@ meshy <resource> list [--page-size <n>] --output-schema v1
   `result.task_id` / `result.submission.task_id` and `result.next` from any
   non-zero exit (11 local I/O, 8 timeout, 130 interrupt) before deciding
   anything; never create again because a later step failed.
+- `-o <dir>` saves the primary files of a SUCCEEDED task (model formats it produced,
+  thumbnail, images, the rig/animation result in GLB) plus `meta.json`; `-o <file.ext>`
+  saves the one file of that format (`-o car.glb`, `-o hero.fbx` on a rig). Texture
+  maps a GLB already embeds, the rig's bundled walking/running clips and FBX copies
+  stay on the server, listed in `result.downloads.skipped`; `--all-assets` (directory
+  only) saves them too. Between pipeline steps pass the task id
+  (`--input-task-id`, `--rig-task-id`) instead of downloading.
 - `--save-json <file>` stores the raw API task (use it as the input of `download`,
   `inspect faces` and `project record`); `--include-raw` puts the raw response under
   `result.task.raw`; `--project <dir>` records the task in a project folder.
@@ -90,14 +98,14 @@ meshy <resource> list [--page-size <n>] --output-schema v1
 ## Creative Lab, UV, catalog, showcases
 
 ```bash
-meshy uv-unwrap create --input-task-id <id> --async --output-schema v1              # GLB only, ≤40k faces (server enforces)
-meshy creative-lab <figure|vinyl-figure|brick-figure|lamp|keychain|fridge-magnet|keycap|fidget-pixel> prototype create --image-url ./photo.png --name demo --async --output-schema v1
-meshy creative-lab <product> build create --input-task-id <prototype-id> [--model-format …] [--options '<json>'] --async --output-schema v1
-meshy creative-lab fidget-collapsible create --image-url ./photo.png --async --output-schema v1   # one stage → STL
-meshy animation-catalog list --category DailyActions --search wave --output-schema v1   # free; search is server-side
-meshy auto-split create --input-task-id <id> --mode by_parts --prompt "head, torso" --async --output-schema v1   # printable parts
-meshy usage tasks --start-time 2026-08-01T00:00:00Z --output-schema v1                 # Studio/Enterprise; credits per task
-meshy showcases list --search car --page-size 3 --output-schema v1                      # Enterprise only; EVERY request is billed
+meshy uv-unwrap create --input-task-id <id> --async              # GLB only, ≤40k faces (server enforces)
+meshy creative-lab <figure|vinyl-figure|brick-figure|lamp|keychain|fridge-magnet|keycap|fidget-pixel> prototype create --image-url ./photo.png --name demo --async
+meshy creative-lab <product> build create --input-task-id <prototype-id> [--model-format …] [--options '<json>'] --async
+meshy creative-lab fidget-collapsible create --image-url ./photo.png --async   # one stage → STL
+meshy animation-catalog list --category DailyActions --search wave   # free; search is server-side
+meshy auto-split create --input-task-id <id> --mode by_parts --prompt "head, torso" --async   # printable parts
+meshy usage tasks --start-time 2026-08-01T00:00:00Z                 # Studio/Enterprise; credits per task
+meshy showcases list --search car --page-size 3                      # Enterprise only; EVERY request is billed
 ```
 
 Prototype meanings differ: most yield a concept image, lamp also yields a
@@ -112,23 +120,24 @@ Never call `showcases` in a health check.
 ## Downloads, projects, printing (local, no key)
 
 ```bash
-meshy download --task-json ./task.json --list --output-schema v1
-meshy download --task-json ./task.json --model-format glb --output ./model.glb --output-schema v1
-meshy download --task-json ./rig.json --asset result.basic_animations.walking_glb_url --output ./walking.glb --output-schema v1
-meshy download --resource image-to-3d --task-id <id> --all --output-dir ./out/ --output-schema v1
-meshy project init --root ./meshy_output --name "<prompt>" --task-id <id> --output-schema v1
-meshy project record --project <dir> --task-id <id> --resource text-to-3d --stage preview --file preview.glb --output-schema v1
-meshy inspect faces --task-json ./task.json --max-faces 300000 --output-schema v1   # exit 0 pass | 12 fail | 13 unknown
-meshy mesh prepare-print ./model.obj --height-mm 75 --output-schema v1              # writes ./model.print.obj (Y-up → Z-up, grounded)
-meshy slicer detect --output-schema v1
-meshy slicer open --slicer OrcaSlicer --file ./model.print.obj --output-schema v1  # launch only; not proof of import
+meshy download --task-json ./task.json --list
+meshy download --task-json ./task.json --model-format glb --output ./model.glb
+meshy download --task-json ./rig.json --asset result.basic_animations.walking_glb_url --output ./walking.glb
+meshy download --resource image-to-3d --task-id <id> --all --output-dir ./out/
+meshy project init --root ./meshy_output --name "<prompt>" --task-id <id>
+meshy project record --project <dir> --task-id <id> --resource text-to-3d --stage preview --file preview.glb
+meshy inspect faces --model ./model.glb --max-faces 300000      # exit 0 pass | 12 fail | 13 unknown
+meshy mesh prepare-print ./model.obj --height-mm 75              # writes ./model.print.obj (Y-up → Z-up, grounded)
+meshy slicer detect
+meshy slicer open --slicer OrcaSlicer --file ./model.print.obj  # launch only; not proof of import
 ```
 
 `download` needs an explicit selector when a task has several assets (it lists
 them and exits 2 otherwise); it never overwrites without `--overwrite`. `inspect
-faces` answers only the face-count question — `unknown` (exit 13) means the task
-carries no usable `face_count`; do not treat it as a pass and do not start a
-remesh unless the user agrees. `prepare-print` never edits the input unless
+faces` answers only the face-count question. The API does not report
+`face_count`, so measure the downloaded model with `--model <file.glb>`; a task
+source answers `unknown` (exit 13) — never treat that as a pass, and do not
+start a remesh unless the user agrees. `prepare-print` never edits the input unless
 `--in-place`.
 
 ## Constraints that will bite
@@ -161,12 +170,12 @@ These are API rules, not preferences — ignoring them produces failed tasks:
 - `multi-image-to-3d` takes 1-4 views of one object; use `image-to-3d` unless
   multi-view input was asked for. Both accept `--input-task-id` of a SUCCEEDED
   `text-to-image` / `image-to-image` task, so a generated image chains to 3D.
-- `image-to-3d` defaults to an untextured draft mesh; `--should-texture true`
-  (what `make` uses) produces a textured model in one task.
+- `image-to-3d` and `multi-image-to-3d` texture by default, like the API (one
+  task, full PBR maps, 4k base color). `--should-texture false` is an untextured
+  draft to confirm first; texture it later with `retexture`.
 - **The default model is `latest` = Meshy 7.1** on all three generators.
   `--geometry-resolution 2k|4k` runs the Ultra geometry pass (+5 credits;
-  text-to-3d: preview only; multi-image: `2k` only; not with smart-topology);
-  `--ultra-mode` on image-to-3d is its deprecated spelling of `2k`.
+  text-to-3d: preview only; multi-image: `2k` only; not with smart-topology).
   `--model-type smart-topology` (text-to-3d and image-to-3d) has a native
   `--target-polycount`: meshy-t2.5 is the CLI default, 100-30000 (default
   15000); `--ai-model meshy-t2` selects T2, 100-15000 (default 10000). `retexture`'s
@@ -184,8 +193,8 @@ These are API rules, not preferences — ignoring them produces failed tasks:
 ## Finding an animation id
 
 `--action-id` is an integer from Meshy's animation library. Ask the live
-library (free): `meshy animation-catalog list --category Fighting --search kick
---output-schema v1` → `result.items[].action_id`; `--action-ids 92,4` checks
+library (free): `meshy animation-catalog list --category Fighting --search kick` →
+`result.items[].action_id`; `--action-ids 92,4` checks
 stored ids. Ids are not `1..N` (the catalog contains `-2`, `-1` and `0`) — never
 guess one. This skill also bundles a
 snapshot as `animation-library.json` (with hand-written descriptions the API does
@@ -213,8 +222,6 @@ Exit codes: `0` ok · `1` task FAILED/CANCELED while waiting, or unclassified ·
   `result.downloads.files` lists what already landed (`status: written`), the rest can
   be fetched with `meshy download`. `downloads.failed_step` (`relink` | `digest` |
   `sidecar`) means every asset is on disk and only that step is missing.
-- Legacy-schema errors (no `--output-schema v1`) after a create carry additive
-  `task_id` / `operation_id` fields and a `hint` with the resume command — never re-create.
 - `result.downloads.material_links.status: "incomplete"` → name the references that
   stayed unresolved or ambiguous (`texture_maps[].method`, `note`) instead of claiming the
   model loads; two material groups that would share one texture without evidence are
@@ -223,7 +230,7 @@ Exit codes: `0` ok · `1` task FAILED/CANCELED while waiting, or unclassified ·
   disk (`result.downloads.files`); repair the project's `metadata.json`, then run
   `error.recovery.command` (`meshy project record …`, it already carries the original
   `--workspace` and `--operation-id`) verbatim — do not download or create again. The same
-  command appears after a task verb's `--project` record failure (legacy: `hint`); when the
+  command appears after a task verb's `--project` record failure; when the
   error says the project is *no longer a target inside the authorised boundary* (it moved
   mid-request) there is deliberately no command and `recovery` is null — restore the
   directory first, then record with `meshy project record` from inside the original workspace.
@@ -235,9 +242,6 @@ Exit codes: `0` ok · `1` task FAILED/CANCELED while waiting, or unclassified ·
 - A `FAILED` task → relay `result.task.task_error.message` verbatim; do not guess a cause.
 - Any error may carry `error.recovery.command` — prefer it over improvising.
 
-Legacy JSON output (without `--output-schema v1`) may carry `_notice.update` when
-a newer meshy-cli exists; pass its `command` on to the user.
-
 ## Docs
 
 Endpoint reference and pricing: https://docs.meshy.ai/en/api/

package/dist/internal/report.d.ts

@@ -1,40 +0,0 @@
-/**
- * Human-readable status report printed when `-o` is in play.
- *
- * Format:
- *     Status: SUCCESS | FAIL
- *     Task Id: <id>
- *     Generated <type>
- *     Saved to:
- *     - <path>
- *     - <path>
- *     Metadata path: <path>
- *     [optional update notice line when a newer version is available]
- *
- * Success reports list every saved file and the meta.json path. Failure
- * reports include the task_error.message (if present) and skip the Saved
- * to / Metadata path lines since nothing is written.
- */
-import type { Task } from "../client/types.js";
-import type { UpdateNotice } from "./update-notifier.js";
-export interface SuccessReport {
-    status: "SUCCESS";
-    taskId: string;
-    type: string;
-    savedFiles: string[];
-    metadataPath: string;
-    _notice?: UpdateNotice;
-}
-export interface FailReport {
-    status: "FAIL";
-    taskId: string;
-    type: string;
-    error?: string;
-    timedOut?: boolean;
-    _notice?: UpdateNotice;
-}
-export type Report = SuccessReport | FailReport;
-export declare function formatReport(r: Report): string;
-export declare function printReport(r: Report): void;
-export declare function reportFromTask(task: Task, resource: string): Pick<Report, "taskId" | "type">;
-//# sourceMappingURL=report.d.ts.map

package/dist/internal/report.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/internal/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,UAAU,CAAC;AAEhD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB9C;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC,CAK5F"}

package/dist/internal/report.js

@@ -1,48 +0,0 @@
-/**
- * Human-readable status report printed when `-o` is in play.
- *
- * Format:
- *     Status: SUCCESS | FAIL
- *     Task Id: <id>
- *     Generated <type>
- *     Saved to:
- *     - <path>
- *     - <path>
- *     Metadata path: <path>
- *     [optional update notice line when a newer version is available]
- *
- * Success reports list every saved file and the meta.json path. Failure
- * reports include the task_error.message (if present) and skip the Saved
- * to / Metadata path lines since nothing is written.
- */
-export function formatReport(r) {
-    const lines = [];
-    lines.push(`Status: ${r.status}`);
-    lines.push(`Task Id: ${r.taskId}`);
-    lines.push(`Generated ${r.type || "(unknown)"}`);
-    if (r.status === "SUCCESS") {
-        lines.push("Saved to:");
-        for (const file of r.savedFiles)
-            lines.push(`- ${file}`);
-        lines.push(`Metadata path: ${r.metadataPath}`);
-    }
-    else {
-        if (r.timedOut)
-            lines.push("Error: polling timed out before the task reached a terminal status");
-        else if (r.error)
-            lines.push(`Error: ${r.error}`);
-    }
-    if (r._notice)
-        lines.push(r._notice.message);
-    return `${lines.join("\n")}\n`;
-}
-export function printReport(r) {
-    process.stdout.write(formatReport(r));
-}
-export function reportFromTask(task, resource) {
-    return {
-        taskId: task.id,
-        type: task.type || resource,
-    };
-}
-//# sourceMappingURL=report.js.map

package/dist/internal/report.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/internal/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAyBH,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC,CAAC;IAEjD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,UAAU;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;IACjD,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;aAC5F,IAAI,CAAC,CAAC,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,CAAC,CAAC,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7C,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAU,EAAE,QAAgB;IACzD,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,EAAE;QACf,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,QAAQ;KAC5B,CAAC;AACJ,CAAC"}