# Dweller Games

> Dweller Games (https://dweller.games) is a store and launcher for games made with AI tools. Players browse, download and auto-update games through the website and the Dweller desktop launcher. Creators (and their AI coding agents) publish games with the `dweller` CLI, GitHub release sync, or the HTTP API.

## Publishing a game (quick path for AI agents)

1. Install the CLI: `curl -fsSL https://dweller.games/install-cli.sh | sh` (Windows: `irm https://dweller.games/install-cli.ps1 | iex`).
2. Authenticate: `dweller login` (opens a browser approval page) or set `DWELLER_TOKEN` (create one at https://dweller.games/settings/tokens).
3. In the game's repo run `dweller init --title "My Game"` to write `dweller.json`, then edit its `builds` list to point at your exported build folders/files.
4. Run `dweller push --version 1.0.0 --notes "First release" --publish-game`.

## Docs

- [Publishing overview](https://dweller.games/docs/index.md)
- [Let your AI publish it](https://dweller.games/docs/ai.md)
- [Builds & store pages](https://dweller.games/docs/publishing.md)
- [dweller CLI](https://dweller.games/docs/cli.md)
- [GitHub integration](https://dweller.games/docs/github.md)
- [dweller.json manifest](https://dweller.games/docs/manifest.md)
- [HTTP API reference](https://dweller.games/docs/api.md)
- [The Dweller launcher](https://dweller.games/docs/launcher.md)

## Full docs

# Let your AI publish it

Dweller was designed so a coding agent (Claude Code, Cursor, Codex, Aider…) can publish and update your game without you touching a browser. The agent installs the `dweller` CLI, signs in once with your approval, and pushes builds.

## Copy-paste prompt

Paste this into your agent from the game's project folder:

```text
Publish this game to Dweller Games (https://dweller.games). Read https://dweller.games/llms.txt first.
1. Install the dweller CLI (curl -fsSL https://dweller.games/install-cli.sh | sh, or on Windows: irm https://dweller.games/install-cli.ps1 | iex).
2. Run `dweller login` and show me the code/URL so I can approve it in my browser.
3. Export release builds for every platform this project supports into a build/ folder
   (one subfolder per platform; for web builds make sure index.html is at the folder root).
4. Run `dweller init` with a good title, tagline, description, tags and engine, and list each build
   folder in dweller.json with its platform and executable.
5. Run `dweller push --version <version> --notes "<what changed>" --publish-game`.
6. Upload a 1280x600 header image and a few 16:9 screenshots with `dweller media`.
Tell me the store URL when you're done.
```

For later updates, the agent only needs:

```text
Bump the version, rebuild every platform into build/, and run
dweller push --version <new version> --notes "<changelog>"
```

Every player's launcher picks up the new version automatically.

## In CI (no browser)

Create a token at [Settings → API tokens](https://dweller.games/settings/tokens) and expose it as `DWELLER_TOKEN`. The CLI reads it automatically, so agents running in CI or a cloud sandbox never need to open a browser.

## Why it works well with agents

* **Non-interactive by default.** Every command takes flags. `dweller login` prints a URL and code for a human to approve, then waits.
* **Clear, actionable errors.** "version 1.2.0 already exists; bump the version number" rather than a stack trace.
* **`--json` output** on every command, so agents can parse results.
* **One manifest.** `dweller.json` stores everything the agent needs to repeat a release.
* **Docs as Markdown.** Every docs page is available as raw Markdown: add `.md` to the URL (e.g. [https://dweller.games/docs/cli.md](https://dweller.games/docs/cli.md)) or read [/llms.txt](https://dweller.games/llms.txt).


---

# dweller CLI

A single static binary for Windows, macOS and Linux. It publishes builds, manages store pages, and is safe for scripts, CI and AI agents to drive.

## Install

```sh
# macOS / Linux
curl -fsSL https://dweller.games/install-cli.sh | sh
```

```powershell
# Windows (PowerShell)
irm https://dweller.games/install-cli.ps1 | iex
```

## Sign in

```sh
dweller login            # prints a URL + code; approve it in your browser
dweller login --token dg_xxx   # or save a personal token
dweller whoami
```

In CI set `DWELLER_TOKEN` instead (create one at [Settings → API tokens](https://dweller.games/settings/tokens)). `DWELLER_API` overrides the API base URL.

## Commands

| Command | What it does |
|---|---|
| `dweller init [--title T] [--slug S] [--tagline …] [--tags a,b] [--engine …]` | Writes `dweller.json` in the current folder (and creates the game if it doesn't exist). |
| `dweller push [paths…] --version V [--notes …\|--notes-file F] [--platform P] [--arch A] [--exec E] [--game slug] [--beta] [--draft] [--publish-game]` | Uploads builds and creates a release. With no paths it uses the `builds` list from `dweller.json`. Folders are zipped automatically. |
| `dweller games` | Lists your games. |
| `dweller create "Title" [--slug S]` | Creates a draft game. |
| `dweller update [--game slug] [--title …] [--tagline …] [--description-file README.md] [--tags …] [--status published\|unlisted\|draft]` | Edits the store page. |
| `dweller media header.png --kind header` | Uploads a header, cover or screenshot (`--kind screenshot` accepts many files). |
| `dweller open [slug]` | Prints the store URL. |
| `dweller version` | Prints the CLI version. |

Every command accepts `--json` for machine-readable output.

## Examples

```sh
# Publish everything listed in dweller.json
dweller push --version 1.4.0 --notes-file CHANGELOG.md

# One-off: a web build folder and a Windows zip
dweller push build/web build/MyGame-windows.zip --version 1.4.1 --notes "Hotfix"

# Explicit platform for an ambiguous file name
dweller push dist/game.zip --platform linux --exec game.x86_64 --version 2.0.0
```

Platform detection from names: `win`/`windows`/`.exe` → Windows, `mac`/`macos`/`darwin`/`.dmg` → macOS, `linux`/`.x86_64`/`.AppImage` → Linux, `web`/`html5` → Web, `.apk` → Android, `.gba` → GBA. Use `--platform` when a name has no hint.


---

# dweller.json manifest

`dweller.json` lives in your project root. `dweller init` writes it; `dweller push` reads it. Commit it so you, your teammates and your AI agent can repeat releases exactly.

```json
{
  "game": "starfall",
  "title": "Starfall",
  "tagline": "Catch falling stars before the night runs out.",
  "description_file": "STORE.md",
  "tags": ["arcade", "cozy", "pixel art"],
  "engine": "Godot 4.7",
  "ai_tools": ["Claude Code"],
  "builds": [
    { "platform": "windows", "path": "build/windows", "exec": "Starfall.exe" },
    { "platform": "macos",   "path": "build/macos/Starfall.app", "arch": "universal" },
    { "platform": "linux",   "path": "build/linux", "exec": "Starfall.x86_64" },
    { "platform": "web",     "path": "build/web" },
    { "platform": "android", "path": "build/Starfall.apk" }
  ]
}
```

| Field | Meaning |
|---|---|
| `game` | The game's URL name on Dweller (`https://dweller.games/games/<game>`). Required for `push`. |
| `title`, `tagline`, `tags`, `engine`, `ai_tools` | Used when `dweller init` or `dweller push` creates the game, and by `dweller update --from-manifest`. |
| `description_file` | Markdown file used for the store description. |
| `builds[].platform` | `windows`, `macos`, `linux`, `web`, `android` or `gba`. |
| `builds[].path` | A file (zip, exe, apk, gba, AppImage) or a folder. Folders are zipped on upload. A `.app` folder is zipped with the bundle at the top level. |
| `builds[].arch` | `x64` (default for desktop), `arm64`, `universal` or `any`. |
| `builds[].exec` | Program to run after unpacking, relative to the build root. Optional: Dweller detects it when there's only one candidate. |


---

# GitHub integration

Connect a repository and every **GitHub Release** you publish becomes a Dweller release: assets are copied to the Dweller CDN, the tag becomes the version, the release body becomes the notes, and every player's launcher updates.

## Set it up (2 minutes)

1. Open your game on the [dashboard](https://dweller.games/dashboard) → **GitHub** tab.
2. Enter the repository (`owner/name`). For private repos, add a fine-grained token with **read-only access to Contents** on that repo.
3. Leave **Check for new releases automatically** on. Dweller checks about every 10 minutes, no webhook needed.
4. Click **Import latest release now** to pull your current release immediately.

### Instant imports (optional webhook)

The GitHub tab shows a webhook URL and secret. In the repo: **Settings → Webhooks → Add webhook**, paste both, content type `application/json`, and select only the **Releases** event. New releases then import within seconds.

## Naming your release assets

Dweller picks the platform from each asset's file name:

| Asset name contains | Platform |
|---|---|
| `windows`, `win`, or ends in `.exe`/`.msi` | Windows |
| `mac`, `macos`, `darwin`, `osx`, or ends in `.dmg` | macOS |
| `linux`, or ends in `.AppImage`/`.x86_64`/`.deb` | Linux |
| `web`, `html5`, `wasm` | Web (playable in browser) |
| ends in `.apk` | Android |
| ends in `.gba` | Game Boy Advance |

`arm64`/`aarch64` and `universal` in the name set the architecture. Checksums, signatures and text files are ignored.

Example release: `v1.3.0` with assets `Starfall-windows.zip`, `Starfall-macos-universal.zip`, `Starfall-linux.zip`, `Starfall-web.zip`.

## Building in GitHub Actions

Prefer to build in CI and push directly? Use the CLI with a `DWELLER_TOKEN` repository secret:

```yaml
name: Release to Dweller
on:
  push:
    tags: ['v*']
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # …build your game into build/windows, build/linux, build/web…
      - run: curl -fsSL https://dweller.games/install-cli.sh | sh
      - run: ~/.local/bin/dweller push --version "${GITHUB_REF_NAME#v}" --notes-file CHANGELOG.md
        env:
          DWELLER_TOKEN: ${{ secrets.DWELLER_TOKEN }}
```

## Sign in with GitHub

If the site operator has enabled it, you can sign up and sign in with your GitHub account, and link GitHub to an existing account under **Settings → Email & password**.


---