Tooling

Metaloot CLI

@metaloot/cli installs the metaloot command: deploy games to Metaloot hosting, let local agents drive headless Blender, manage Studio assets, and script the whole platform. Requires Node.js 20+.

Installation#

npm install -g @metaloot/cli    # global install
metaloot --version

# or run it without installing:
npx @metaloot/cli deploy

Signing In#

metaloot login       # opens your browser to approve this machine
metaloot whoami      # verify who is signed in
metaloot logout      # revoke this machine's token

login opens the portal in your browser and hands a CLI token (mtl_cli_…, full access) back to the terminal over a loopback redirect. Credentials are stored with owner-only permissions in ~/.config/metaloot/credentials.json, keyed by portal origin. logout revokes the token server-side before deleting it locally.

For CI, agents, or headless machines, skip the browser:

metaloot login --token mtl_api_…       # store a token created at /settings/api-tokens
# or per-invocation, nothing stored:
METALOOT_TOKEN=mtl_api_… metaloot deploy

Scoped API tokens (mtl_api_…) work everywhere CLI tokens do, restricted to their scopes — see API Tokens.

Command Reference#

metaloot deploy

Build and publish the current folder to https://<slug>.metaloot.app. Details in Hosting & Deploys.

--game <game-id>	Deploy to an existing game created on the portal.
--name <name>	Set the game title on first deploy.
--dir <folder>	Folder to upload (must contain `index.html`). Defaults: configured `outDir`, then `dist`, then `build`. Use `--dir .` for plain HTML projects.
--no-build	Skip running the project's build script.
--force	Allow this folder to replace an owned game not pinned by its metaloot.json. Ownership is always enforced.

metaloot blender

The recommended 3D asset workflow. A coding agent running on your computer discovers Metaloot templates and starter assets, writes a bpy script, and submits it to a bounded headless Blender worker. Metaloot validates and returns the GLB, preview, inspection report, and editable .blend artifact. Full walkthrough in Assets.

metaloot blender templates --json
metaloot blender library --json

metaloot blender create \
  --name "Clockwork Gate" \
  --template scene.blank.v1 \
  --starter material.painted-metal \
  --script ./build_gate.py \
  --wait --json

blender health / capabilities	Inspect live worker capacity, supported actions, inputs, artifacts, and limits.
blender templates	List versioned `.blend` starting scenes, parameters, recommended starters, quality tier, and agent-specific guidance. Add `--json` for machine-readable discovery.
blender library [query]	Search materials, models, base meshes, kitbash parts, Geometry Nodes groups, lighting, HDRIs, and community collections. Filters: `--kind`, `--category`, `--json`.
blender create	Create a Studio asset from an agent-authored `--script <file.py>`. Select one `--template`, repeat `--starter` as needed, and optionally pass `--parameters`, `--param key=value`, `--face-limit`, `--visibility`, `--wait`, and `--json`.
blender revise <asset-id>	Run another `bpy` script against an existing Blender-backed Studio asset and save the result as a new asset.
blender jobs / status / cancel	List owner-scoped jobs, poll one to completion, or cancel queued and running work.
blender action <job-id>	Run `revise`, `render`, `inspect`, or `export` against a completed worker job; accepts another agent-authored script.
blender artifacts / download	List or download `model.glb`, `preview.png`, `inspection.json`, and `scene.blend`.

The local agent authors the asset. Metaloot does not run a remote prompt-to-Blender agent. Passing --scriptgives the job access to Blender's headless Python API plus the selected starter data blocks.

metaloot assets

Browse, publish, rig, download, and consume Studio assets. The legacy Tripo generation command also remains here temporarily. Full walkthrough in Assets:

assets generate	Legacy Tripo-backed text-to-3D and image-to-3D interface. Retained for compatibility and planned for removal in a future release. Use `metaloot blender` for new workflows.
assets status <id>	Check a generation or rig job. `--wait` blocks until finished.
assets rig <id>	Auto-rig a finished model and retarget preset clips: `--presets idle,walk,run` (the default), `--wait`, `--json`.
assets list / assets explore	Your assets / the public gallery. Filters: `--category <c>`, `--kind model3d\|image\|video\|audio\|sprite\|texture\|animation`, `--json`.
assets files <pack-id>	List every hosted file in a pack: path, MIME type, size, SHA-256.
assets download <id>	Save the asset locally. `--dir <folder>` (default `assets/metaloot/`), `--variant source\|lod`, `--path <pack-file>` for one file from a pack.
assets publish / unpublish <id>	Flip an asset between public (hot-linkable, in Explore) and private.
assets update <id>	Edit asset metadata.

Global flags

--help, -h	Show usage.
--version, -v	Show the CLI version.
--json	On `generate, list, explore, files, status, rig`: print a machine-readable JSON object last on stdout, after the human-readable lines. Commands exit non-zero on failure, so they chain safely in scripts.

Configuration#

Files

metaloot.json	Per-project, next to `package.json`: `{ gameId, slug, name, outDir }`. Written on first deploy — commit it.
~/.config/metaloot/credentials.json	Stored login tokens, keyed by portal origin, written with mode 0600.

Environment variables

METALOOT_TOKEN	Token override (`mtl_api_…` or `mtl_cli_…`) — takes precedence over stored credentials. The way to authenticate in CI.
METALOOT_ORIGIN	Portal origin (default `https://www.metaloot.app`) — for local platform development.
METALOOT_STUDIO_ORIGIN	Studio origin for `assets` and `blender` commands (default `https://studio.metaloot.app`).
METALOOT_CONFIG_DIR	Credentials directory (default `~/.config/metaloot`).

Everything the CLI does goes through the public HTTP API with the same tokens — see the API Reference if you need to call it without the CLI.