town

town [command] [options]town {login | new | clone | deploy | catalog | delete | generate | test | init} [args] [options]

town is the companion command-line tool for Town (by RedPlanetHQ / CORE): multiplayer pixel-map spaces where each building hosts AI characters with personalities and tool skillsets. Players explore towns in the browser; creators edit towns as a folder of JSON and MDX on disk, then push changes with this CLI.A town folder typically contains town.json (building list and custom plot refs), npcs/ (one .mdx file per character, frontmatter for identity and body as the system prompt), optional customPlots/ (user-defined interiors/exteriors), plus catalog/manifest reference files. Bare town with no subcommand, run inside a folder that has town.json, launches the interactive chat creator (requires prior town login). Outside a town folder, bare town prints help.Authentication uses a CORE personal access token stored at ~/.town/config.json (mode 0600). API calls send that token as a Bearer credential to the configured town server.

deploy options:-d, --dir path

Folder containing town.json, customPlots/, and npcs/ (default: current directory).

Target town slug (defaults from town.json id stash, then folder name).

Wipe the server-side plot before applying so layout is regenerated from scratch.

Credentials and optional LLM keys live in ~/.town/config.json (directory ~/.town/, file permissions 0600):

$ {
  "auth": {
    "coreUrl": "https://app.getcore.me",
    "townUrl": "https://town.getcore.me",
    "pat": "<CORE personal access token>"
  },
  "llm": {
    "provider": "anthropic",
    "anthropicKey": "...",
    "openaiKey": "...",
    "ollamaKey": "..."
  }
}

login

Authenticate with CORE (browser OAuth flow) and save host URLs plus PAT under ~/.town/config.json.

Create a new town (prompts for a name when omitted), scaffold the local folder, and launch the chat creator.

Pull an existing town's state into a local directory. Use --slug to pick a town without an interactive prompt.

Upload town.json, customPlots/, and npcs/ to the server. Uploads new local PNGs, then POSTs the plot payload; the server applies incremental layout ops by default.

Print available plot keys from the global catalog; with --slug, include that town's tags and item templates.

Permanently delete one of your towns. --force skips the type-the-slug confirmation.

Generate a pixel-art PNG for a custom plot exterior or interior from a short text description.

Store an LLM API key for local NPC testing (anthropic, openai, or ollama). Environment variables always override saved keys.

Run an NPC prompt against a real model (multi-turn session, one-shot question, or scripted scenario).

Deprecated alias. Exits with a message to use town new or town clone instead.

Requires Node.js (the published package targets modern Node and is typically run via npm / pnpm). Most mutating commands need a successful town login. town init no longer creates or clones towns — use new or clone. Sprite uploads on deploy accept PNG only (content-addressed, size-capped on the server). town test npc needs a configured LLM key and may incur provider costs. The interactive creator TUI expects a real terminal.

Town is an open-source project from RedPlanetHQ, built around the CORE agent/memory platform. Towns are multiplayer pixel maps with tool-using AI NPCs; the @redplanethq/town package provides the offline authoring and deploy workflow. Early CLI versions used a single init verb for both create and clone; that was later split into town new and town clone, with init retained only as a migration hint.

npm(1), pnpm(1), node(1)

Source code · Homepage · Documentation