# 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 instead:

```powershell
npm install -g https://mable-dev-service-gamma.mable.gg/cli/mable-cli.tgz
```

If `mable` is not found there, use `npx -y 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. Do not send the `verification` code in its place: the authorization page accepts only the pairing code. After they sign in or create an account, enter the pairing code and click Authorize, run `mable-gamma login` to finish. 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.

## 3. Read the skill and confirm the platform

Before generating or publishing anything, read the skill at https://webtest-gamma.mable.gg/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. Use the person's stated choice; if it is unspecified, ask before creating the project. Mobile games need touch controls. Desktop games are link-only (unlisted); tell players to open the link on a computer. 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
mable-gamma resume --last
```

Use the returned GLB and inspect its metadata: the model may be a static mesh or have a skeleton, depending on the active pipeline. 3D animation generation is unavailable in this release. 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 --title "My Game"
mable-gamma games
mable-gamma stats
```

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. Publishing returns an unlisted playable link; share that link with the person. Right after publishing a mobile game, ask the person one clear question: "Make it public on Mable so people who don't have the link can find and play it? It goes through Mable's content review first." Recommend yes: an unlisted game is only played by people the person sends the link to. Run `--public` once the person says yes (or right away if they already asked for public distribution); if they say no, do not ask again for that game; server playtest and content review still apply. 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.

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.