# 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.mable.gg/cli/install.sh | sh
```

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

If `mable` is already installed, compare `mable --version` with the latest version at https://mable-dev-service.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 https://mable-dev-service.mable.gg/cli/mable-cli.tgz
mable skill install
```

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

## 2. 检查并复用登录

1. 先运行 `mable whoami --json`。成功时直接继续第 3 节，使用返回的账号，不要再运行 login 或发送登录链接。本地凭据会跨终端 tab 和项目保存。
2. 只有错误码为 `NOT_LOGGED_IN` 或 `AUTH_REJECTED` 时，才运行 `mable login --no-wait`。退出码 3 表示等待浏览器授权；退出码 0 表示已经登录，直接继续。网络或服务错误不代表未登录，应报告原错误并重试检查。
3. 仅在等待授权时，把命令打印的登录链接和确认码发给用户。用户登录或注册并点击 Authorize 后，运行 `mable login` 完成授权。用户明确要求换账号时才使用 `mable login --new`。


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://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.mable.gg/cli/skill/SKILL.md.


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 gen model3d --image hero.png --id hero --async
mable 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 init my-game --template canvas --platform mobile
cd my-game
mable preview
mable check
mable publish --title "My Game"
mable games
mable 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. Use `--public` only for a mobile game when the person explicitly asks for public distribution; 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 update`, then check `mable help` and the current skill. Report a server-disabled feature as unavailable instead of bypassing it.