@meshy-ai/cli 0.1.0

package/dist/root.js

@@ -0,0 +1,148 @@
+/**
+ * Root command. Wires global flags and attaches every subcommand.
+ *
+ * The per-endpoint commands are registered but hidden from the root help.
+ * They remain fully supported — `meshy resources` indexes them and
+ * `meshy <resource> --help` documents each one. The root help leads with the
+ * short list instead, because it is read on every invocation (an agent pays
+ * for the whole surface each time it runs `--help`), and because a caller who
+ * wants one model should not have to pick an endpoint first.
+ */
+import { Command } from "commander";
+import { VERSION } from "./internal/version.js";
+import { REFRESH_COMMAND, runRefreshCommand } from "./internal/update-notifier.js";
+import { mirrorGlobalOptionsToDescendants, registerRootGlobalOptions, } from "./internal/global-options.js";
+import { analyzePrintabilityCommand } from "./cmd/analyze-printability.js";
+import { animateCommand } from "./cmd/animate.js";
+import { apiCommand } from "./cmd/api.js";
+import { authCommand } from "./cmd/auth.js";
+import { balanceCommand } from "./cmd/balance.js";
+import { convertCommand } from "./cmd/convert.js";
+import { deleteCommand } from "./cmd/delete.js";
+import { imageTo3dCommand } from "./cmd/image-to-3d.js";
+import { imageToImageCommand } from "./cmd/image-to-image.js";
+import { makeCommand } from "./cmd/make.js";
+import { multiColorPrintCommand } from "./cmd/multi-color-print.js";
+import { multiImageTo3dCommand } from "./cmd/multi-image-to-3d.js";
+import { remeshCommand } from "./cmd/remesh.js";
+import { repairPrintabilityCommand } from "./cmd/repair-printability.js";
+import { resizeCommand } from "./cmd/resize.js";
+import { resourcesCommand } from "./cmd/resources.js";
+import { retextureCommand } from "./cmd/retexture.js";
+import { riggingCommand } from "./cmd/rigging.js";
+import { textTo3dCommand } from "./cmd/text-to-3d.js";
+import { textToImageCommand } from "./cmd/text-to-image.js";
+const ROOT_LONG = `meshy-cli — command-line interface for the Meshy AI API.
+
+USAGE:
+    meshy make <prompt | image> [-o <path>]  # the short path to a model
+    meshy <resource> <action> [flags]        # one endpoint at a time — meshy resources
+    meshy api <METHOD> <PATH> [--data <json>]
+
+EXAMPLES:
+    # one command, one model (sync: returns when the model is done)
+    meshy make "a red sports car" -o car.glb
+    meshy make ./cat.png -o out/cat/
+    meshy make "a red sports car" --dry-run        # steps + estimate, no spend
+    meshy make "a red sports car" --max-credits 25 # refuse if the estimate is over
+
+    # every endpoint, one at a time
+    meshy resources                                # index of the 16 commands
+    meshy text-to-3d create --mode preview --prompt "a red sports car"
+    meshy image-to-3d get <task-id>
+    meshy delete <task-id>                         # unified: works for any task
+
+    # escape hatch for endpoints without a dedicated subcommand
+    meshy api GET /balance
+    meshy api POST /text-to-3d --data '{"mode":"preview","prompt":"car"}'
+
+AUTHENTICATION:
+    auth login                       open the browser for OAuth login (loopback + PKCE)
+    auth login --with-key msy_...    paste an existing API key instead of the browser flow
+    auth status                      which credential is in effect, and does it work
+    auth list                        stored profiles
+    auth use <profile>               switch the active profile
+    auth logout [--all]              forget the stored credential
+
+    Resolution order: --api-key > MESHY_API_KEY > stored profile. The env var
+    stays ahead of the stored credential so CI is never overridden by whatever
+    a developer logged into on that machine. Non-production --base-url-v1 uses a
+    separate credentials.dev.json, so staging cannot clobber a production login.
+
+RESOURCE COMMANDS:
+    All 16 endpoint commands stay available and stay supported — they are
+    indexed by \`meshy resources\` instead of listed here, so this help does not
+    grow with the API. \`meshy resources --help\` also carries the shared
+    create/get/list/wait/delete verb contract.
+
+GLOBAL FLAGS (accepted at any position in the command line):
+    --api-key <key>          override MESHY_API_KEY
+    --base-url-v1 <url>      override MESHY_BASE_URL_V1
+    --base-url-v2 <url>      override MESHY_BASE_URL_V2
+    --format <fmt>           json (default) | pretty | ndjson
+    --output, -o <path>      download task artifacts to a file or directory,
+                             write meta.json alongside, and replace stdout
+                             with a status report (without -o: stdout keeps
+                             the JSON summary).
+    --verbose, -v            enable debug logging to stderr
+    --log-level <level>      debug | info | warn | error | silent
+
+ENVIRONMENT:
+    MESHY_API_KEY                      required unless a profile is stored
+    MESHY_CONFIG_DIR                   default: ~/.config/meshy
+    MESHY_CREDENTIALS_PATH             exact credentials file (wins over the above)
+    MESHY_BASE_URL_V1                  default: https://api.meshy.ai/openapi/v1
+    MESHY_BASE_URL_V2                  default: https://api.meshy.ai/openapi/v2
+    MESHY_OAUTH_AUTHORIZE_URL          override the OAuth authorize page (staging/testing)
+    MESHY_CLI_NO_BROWSER               set to 1 to skip browser open (headless/agent use)
+    MESHY_POLL_INTERVAL_MS             default: 3000
+    MESHY_READ_TIMEOUT_MS              default: 120000
+    MESHY_LOG_LEVEL                    default: warn
+    MESHY_CLI_NO_UPDATE_NOTIFIER       set to disable update checks
+
+Docs: https://docs.meshy.ai/`;
+export function buildRootCommand() {
+    const program = new Command();
+    program
+        .name("meshy-cli")
+        .description(ROOT_LONG)
+        .version(VERSION, "-V, --version")
+        .showHelpAfterError();
+    registerRootGlobalOptions(program);
+    // Listed in the root help.
+    program.addCommand(makeCommand);
+    program.addCommand(authCommand);
+    program.addCommand(balanceCommand);
+    program.addCommand(resourcesCommand);
+    program.addCommand(apiCommand);
+    // Registered and supported, but indexed by `meshy resources` rather than
+    // printed on every --help. Hiding is a help-text decision only: these keep
+    // working exactly as before, and the surface tests walk them either way.
+    for (const cmd of [
+        textTo3dCommand,
+        imageTo3dCommand,
+        multiImageTo3dCommand,
+        remeshCommand,
+        convertCommand,
+        resizeCommand,
+        riggingCommand,
+        animateCommand,
+        retextureCommand,
+        textToImageCommand,
+        imageToImageCommand,
+        multiColorPrintCommand,
+        analyzePrintabilityCommand,
+        repairPrintabilityCommand,
+        deleteCommand,
+    ]) {
+        program.addCommand(cmd, { hidden: true });
+    }
+    // Hidden self-command used by the detached background cache-refresh child.
+    // commander v13: .command(name, { hidden: true }) with NO description arg.
+    program.command(REFRESH_COMMAND, { hidden: true }).action(async () => {
+        await runRefreshCommand();
+    });
+    mirrorGlobalOptionsToDescendants(program);
+    return program;
+}
+//# sourceMappingURL=root.js.map

package/dist/root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.js","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@meshy-ai/cli",
+  "version": "0.1.0",
+  "description": "Official command-line interface for the Meshy AI API — text-to-3D, image-to-3D, remesh, rigging, animate, retexture, 2D images, multi-color print, balance.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@11.18.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meshy-dev/meshy-cli.git"
+  },
+  "homepage": "https://github.com/meshy-dev/meshy-cli#readme",
+  "bugs": {
+    "url": "https://github.com/meshy-dev/meshy-cli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "meshy",
+    "meshy-ai",
+    "cli",
+    "3d",
+    "text-to-3d",
+    "image-to-3d",
+    "rigging",
+    "animation"
+  ],
+  "bin": {
+    "meshy-cli": "./dist/index.js",
+    "meshy": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".env.example",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "tsx --test tests/**/*.test.ts",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "prepare": "test -f dist/index.js || npm run build",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "sharp": "^0.34.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/skills/meshy-cli/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: meshy-cli
+description: "Generate 3D models and 2D images with the Meshy API through the meshy-cli command — text-to-3D, image-to-3D, remesh, rigging, animation, retexture, printability. Use for any Meshy asset request."
+license: MIT
+compatibility: Requires meshy-cli on PATH and a stored credential or MESHY_API_KEY; network access to api.meshy.ai
+metadata:
+  version: "1.0.0"
+  cli-help: "meshy --help"
+---
+
+# meshy-cli
+
+## Setup
+
+`npm i -g meshy-cli`, then `meshy auth login` (browser) or
+`meshy auth login --with-key msy_...`. `MESHY_API_KEY` also works and wins over
+a stored profile, which is what CI wants. Never echo the key back or write it
+into a shell profile.
+
+## One model, one command
+
+```bash
+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
+meshy make "..." --max-credits 25            # refuse to start over budget
+```
+
+The input decides the chain and nothing else does. If step 2 fails, the error's
+`hint` is the command that resumes from step 1's task — run it verbatim rather
+than starting over, or the finished step is paid for twice.
+
+## Everything else
+
+`meshy resources` indexes the 16 endpoint commands; each carries the same verbs:
+
+```bash
+meshy <resource> create [flags] [--data '<json>'] [--async] [--timeout <s>]
+meshy <resource> get|wait|delete <task-id>
+meshy <resource> list [--page-size <n>]
+```
+
+`create` blocks until the task is terminal; `--async` returns the id instead.
+`-o <path>` downloads artifacts (a directory for multi-file results) and writes
+a `meta.json` sidecar; without `-o`, stdout is the task JSON — parse ids from
+there, never from text shown in chat. `--data '<json>'` reaches any field the
+CLI has no flag for, and `meshy api <METHOD> <PATH>` reaches any endpoint it has
+no command for.
+
+## Constraints that will bite
+
+These are API rules, not preferences — ignoring them produces failed tasks:
+
+- **`refine` only works on a `text-to-3d` preview** (it consumes that task's
+  latents). Uploaded models, `image-to-3d` output and remeshed meshes are
+  textured with `retexture` instead.
+- **`rigging` needs a textured biped GLB** under 300k faces, with clear limbs —
+  not props, quadrupeds or untextured drafts. Too dense? `remesh` first. A
+  successful rigging task already bundles walking and running clips, so check
+  its result before calling `animate`.
+- **`animate` takes a rigging task id**, not a model task id, plus an integer
+  `--action-id`.
+- **`repair-printability` drops textures and invalidates UVs.** Run it before
+  texturing, or re-`retexture` afterwards.
+- **`multi-image-to-3d` is beta**; use `image-to-3d` unless multi-view input was
+  explicitly asked for.
+- `image-to-3d` defaults to an untextured draft mesh; `--should-texture true`
+  (what `make` uses) produces a textured model in one task.
+
+## Finding an animation id
+
+`--action-id` is an integer from Meshy's animation library. Look it up from the
+public catalog — no key required:
+
+```bash
+curl -s "https://api.meshy.ai/web/public/animations/resources" \
+  | jq -r '.result.list[] | select(.category=="Fighting") | "\(.id)\t\(.name)"'
+```
+
+Categories: WalkAndRun, BodyMovements, DailyActions, Fighting, Dancing.
+`?category=Fighting` narrows the response; other query parameters are ignored.
+
+## When something fails
+
+Exit codes: `0` ok · `2` usage · `3` auth · `4` validation · `5` not found ·
+`6` rate limit · `7` network · `8` timed out · `9` out of credits.
+
+- Exit 9 → run `meshy balance`, relay the number, do not retry.
+- Exit 6 → back off; the CLI does not retry for you.
+- A `FAILED` task → relay `task_error.message` verbatim; do not guess a cause.
+- Any error payload may carry `hint` — a command to run. Prefer it over
+  improvising.
+
+JSON object output may also 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/