# mable CLI: setup guide for coding agents

A person wants to build a game, add assets or publish it and pointed you here. `mable` is a command-line tool made for coding agents (Claude Code, Codex, Cursor and others). It generates assets into the project and publishes games with playable share links:

- character images and props
- character sprite animations (sprite sheets)
- visual effects (VFX)
- sound effects
- music
- voice lines
- 3D models (GLB) from a reference image

Do the setup below yourself. The person only needs to sign in once in their browser.

## 1. Install

```sh
curl -fsSL https://mable-dev-service-gamma.mable.gg/cli/install.sh | sh
```

The shell installer creates `mable-gamma`. If it is not found in this shell yet, call it by its full path `~/.local/bin/mable-gamma`.

If `mable-gamma` is already installed, compare `mable-gamma --version` with the latest version at https://mable-dev-service-gamma.mable.gg/cli/version; if it is older, run the install command above again before anything else.

On Windows (PowerShell or cmd, where `curl | sh` does not run), install the npm package and the skill instead:

```powershell
npm install -g --allow-remote=root https://mable-dev-service-gamma.mable.gg/cli/mable-cli.tgz
mable --gamma skill install
```

Keep `--allow-remote=root`: npm 12 refuses to install a package from a URL without it (error EALLOWREMOTE), and older npm ignores it. npm 12 also skips the package's install script, so run the skill install line too.

If `mable` is not found there, use `npx -y --allow-remote=root https://mable-dev-service-gamma.mable.gg/cli/mable-cli.tgz` in its place.

## 2. Check for an existing sign-in and reuse it

1. Run `mable-gamma whoami --json` first. If it succeeds, continue with section 3 using the account it returns; do not run login or send a sign-in link. Local credentials are shared across terminal tabs and projects.
2. Run `mable-gamma login --no-wait` only when the error code is `NOT_LOGGED_IN` or `AUTH_REJECTED`. Exit code 3 means it is waiting for browser approval; exit code 0 means it is already signed in, so continue. A network or service error does not mean the person is signed out: report the original error and retry the check.
3. If the error code is `CREDENTIAL_TARGET_MISMATCH`, the credentials saved on this computer belong to a different API target. Do not retry. Tell the person and let them choose: set `MABLE_CONFIG_DIR` to a separate directory for this target, or run `mable-gamma login --new` to sign in again here.
4. Only while it is waiting for approval, send the person the sign-in link, then send the pairing code (the `pairingCode` field in the JSON output) in a separate message right after it, in the same turn (do not end your turn between the two or after them). Do not send the `verification` code in its place: the authorization page accepts only the pairing code. Tell them to sign in or create an account, enter the pairing code and click Authorize, and that you will continue by yourself; do not ask them to reply when they are done. Right after sending both messages, without ending your turn, run `mable-gamma login` to finish: it waits for the approval and exits 0 once they authorize (exit code 3 means still waiting: run it again). The link and pairing code work for 30 minutes. Only if the person cannot see your messages until your turn ends, ask them to tell you when they have approved, then run `mable-gamma login`. If the link expired, the page reports too many wrong pairing codes, or the person asks to sign in again, run `mable-gamma login --no-wait` again and send the new link and pairing code. Use `mable-gamma login --new` only when the person explicitly asks to switch accounts.

On Windows/npm, run `mable --gamma whoami --json` first; only when approval is needed, use `mable login --gamma --no-wait`, then `mable login --gamma` to finish. In all examples below, replace `mable-gamma` with `mable --gamma`.


Never ask the person for a key, password or token.

Privacy: `mable-gamma login` sends one anonymous "login started" count (CLI version, agent tool, OS and channel code; no hostname, file paths or email) and stores the sign-in link on Mable for 30 minutes to give a short link (the link includes the computer's name). To turn both off, set `MABLE_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`; the sign-in link is then long.

With CLI 0.4.122 or newer, `MABLE_NO_TELEMETRY=1` and `DO_NOT_TRACK=1` also disable optional agent identification and fingerprint headers/metadata. Older versions need `MABLE_NO_AGENT_FINGERPRINT=1` as well to disable detailed fingerprints. Authentication and billing still work.

## 3. Read the skill and confirm the platform

Before generating or publishing anything, read the skill at https://mcp.gamma.tomoai.io/skill.md for when and how to use each command. It is kept up to date with the CLI. The same file is also at https://mable-dev-service-gamma.mable.gg/cli/skill/SKILL.md.

In the game project directory, run `mable-gamma skill install --project` so a new agent session can discover the current instructions. On Windows/npm, run `mable --gamma skill install --project`. This installs the bundled skill into this project's `.claude/skills` and `.agents/skills`, without replacing global production skills. Repeat this step for each new game project, then start a new agent session in that project.


Before starting game work, confirm whether the game targets mobile or desktop. For a new game, use the person's stated choice; if it is unspecified, ask before creating the project. For an existing game, read its controls: if every action works with taps or touch drags (touchstart, pointerdown or click handlers; no keyboard, hover, right-click or mouse aiming needed) and it fills a portrait screen, publish it as a mobile game, so phone players can find it. Use desktop only for games that need a keyboard or mouse or a fixed wide landscape screen, and tell players to open the link on a computer. If you cannot tell (or it is touch-only but landscape), ask the person instead of defaulting to desktop. Keep the chosen platform in `mable.json` and check the platform printed by init, check, publish, games and stats.

## 4. Generate a 3D model when needed

Read the skill's model3d reference first. Use a clear image of one complete subject, then run:

```sh
mable-gamma gen model3d --image hero.png --id hero --async
```

Read the status in the result:

- `awaiting_human_selection`: Mable needs the person to approve this exact request first, and no job has started yet. Send them the `approvalUrl` from the result and ask them to approve it in Mable; do not approve it yourself. After they approve, run the same `gen model3d` command again (same image and `--id`) to start the job. `mable-gamma resume` cannot collect it before then.
- Running (exit code 3): collect it later with the command in the result's `resume` field, or `mable-gamma resume <jobId>` with the returned job ID. Do not rely on `resume --last` when other assets were started since.

Use the returned GLB and inspect its metadata: the model may be a static mesh or have a skeleton, depending on the active pipeline. For animation, follow the skill's model3d reference. Verify the model and textures load in the actual game before publishing.

## 5. Build, check and publish

Read the skill's publishing reference before starting. For a new mobile project:

```sh
mable-gamma init my-game --template canvas --platform mobile
cd my-game
mable-gamma preview
mable-gamma check
mable-gamma publish --public --title "My Game"
mable-gamma games
mable-gamma stats
```

For an existing game, skip `init`: run `mable-gamma check . --platform <mobile|desktop>` and `mable-gamma publish . --platform <mobile|desktop> --public` in its folder (or its built folder). Choose `--platform desktop` for a desktop game; use the Three template when the project needs 3D. Implement the game before checking or publishing it. Preview runs until stopped, so run it in the background while editing. Check sends the build for a server playtest, but does not create or publish a game.

Only publish when the person asks to publish or share. "Publish my game" (the request that sent you here) means the person wants it in the Mable feed: run `mable-gamma publish --public` without asking first. Use `mable-gamma publish --unlisted` (link only) only when the person asks for a private or link-only game or says not to make it public. Report what publish printed: "Live (public" means it is in the Mable feed. "public is waiting for Mable's content review" (exit code 3) means it is published and submitted to the Mable feed: wait about a minute and rerun the same `mable-gamma publish --public` a few times; if it is still waiting, tell the person it is in content review and to ask you to run it again later. "Not made public" or "Not eligible for --public until" means it is only a link for now: fix those items, or tell the person why, and do not say it was submitted. Give the playable link and do not promise that it will be in the feed: the server playtest and content review decide. Afterwards, suggest they ask "Who's playing it?"; answer with `mable-gamma stats` (players, players who stayed 30 s, and where they came from when it shows that). Later publishes in the same directory update the linked game. If another version is already online, inspect the conflict details and ask the person before forcing an overwrite.

Unlisted is not access-controlled: anyone with the link can play. If the person needs restricted access, explain that Mable has no private tier before uploading; do not describe an unlisted link as private.

If a command is unavailable, run `mable-gamma update`, then check `mable-gamma help` and the current skill. Report a server-disabled feature as unavailable instead of bypassing it.