Tooling
Metaloot CLI
@metaloot/cli installs the metaloot command: deploy games to Metaloot hosting, generate and 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 deploySigning In#
metaloot login # opens your browser to approve this machine
metaloot whoami # verify who is signed in
metaloot logout # revoke this machine's tokenlogin 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 deployScoped 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. |
metaloot assets
The asset pipeline — full walkthrough in Assets:
| assets generate | Start a text-to-3D (--prompt) or image-to-3D (--image <file|url>) job. --name is required; options: --quality draft|standard|hd, --visibility private|public, --category, --face-limit <n>, --wait, --json. |
| 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 commands (default https://studio.metaloot.app). |
| METALOOT_CONFIG_DIR | Credentials directory (default ~/.config/metaloot). |