CLI Overview

The poe-tiles CLI lets you manage and publish games on the App Platform from your terminal or in automated scripts. It wraps the REST API with a convenient interface, similar to gh for GitHub.

If you'd like to interface with the platform programmatically from code, see Programmatic Usage or the REST API docs.

Installing the CLI

The CLI requires Bun — its entry points are shipped as TypeScript and run by Bun directly.

Installing from a published tarball

Globally install the published tarball:

bun remove -g @ai-app/poe-tiles-cli 2>/dev/null; bun install -g https://misc-dev-uploads.quora-913.workers.dev/2e8ee6e4c2ab80af749cc0b44862d8c3ff8d6e113d28ad7cd98fc6ff3f28825b

This adds poe-tiles to Bun's global bin dir (~/.bun/bin). Ensure that directory is on your PATH, then verify:

poe-tiles --version

The URL above points at the most recent tarball uploaded to misc-dev-uploads. It is regenerated when a new CLI version is published. The tarball is self-contained: production dependencies are plain npm packages and there are no workspace:* references. packaging.test.ts enforces this invariant — shipped source files may only import declared deps or node:* builtins.

Upgrading the CLI

Once installed, the CLI can upgrade itself in place:

poe-tiles upgrade

This fetches the latest tarball manifest from https://poe-app-platform-docs.pages.dev/cli/latest.json, runs bun remove -g @ai-app/poe-tiles-cli, then bun install -g <tarballUrl>. The fetched URL is pinned to the misc-dev-uploads.quora-913.workers.dev host before being passed to bun install -g, so a compromised docs deploy can't redirect installs to an attacker-controlled tarball. Only tarballUrl and publishedAt are read from the manifest — the install command is constructed CLI-side, never sh -c'd from a network string.

Dry run (print the equivalent install command without executing):

poe-tiles upgrade --print

upgrade updates the globally-installed package in ~/.bun/bin.

Checking the version

poe-tiles --version

Authentication

The CLI requires a Poe API key. Get one at poe.com/api/keys, then set it as an environment variable:

export POE_API_KEY=your_key_here

Verify it works:

poe-tiles auth whoami

Available Commands

auth — Authentication & Account Info

poe-tiles auth login              # Verify API key, show user info
poe-tiles auth whoami             # Show current user
poe-tiles auth usage              # Show point balance
poe-tiles auth points-history     # Show usage history table
poe-tiles auth logout             # End session

apps — App Management

poe-tiles apps list               # List all your apps
poe-tiles apps get <appHandleOrId>
poe-tiles apps publish --handle my-app --dir ./dist
poe-tiles apps rename <appHandleOrId> <newHandle>

apps rename — Rename one of your apps

Rewrites the app's handle without re-publishing the bundle. Accepts either the canonical app ID or userHandle/appHandle. New handle must be unique across your apps.

apps publish — App-page metadata flags

apps publish accepts optional metadata fields that decorate the app's landing page and the cards in app listings. Each can be set in .poe-app.json or overridden by a CLI flag (explicit flag wins). Pass an empty value (--profile-picture="", etc.) to clear an existing value on re-publish.

Flag	.poe-app.json field	Notes
--display-name <name>	displayName	Human-friendly name shown on Explore and app cards instead of the kebab-case handle (≤80 chars).
--profile-picture <pathOrUrl>	profilePicture	Local PNG/JPG/WEBP file path (uploaded, ≤512 KB) or an https:// URL stored as-is.
--short-description <text>	shortDescription	One-line tagline (≤140 chars).
--long-description <path>	longDescription	Path to a markdown file (≤16 KB UTF-8). The CLI reads the file contents on publish.

The .poe-app.json schema URL must be v2.json to use any of these fields. Update the $schema value in your config; the previous v1 schema is rejected by the current CLI.

apps publish — Visibility

apps publish --visibility public|unlisted|dev controls whether the app appears in public catalog surfaces. Omit the flag to create public apps by default; on re-publish, omission preserves the current visibility. unlisted apps keep their direct /apps/<user>/<handle> links but are excluded from Explore, For You, search for non-owners, and public profile app lists. dev is an internal/legacy visibility still accepted by the publish plumbing; prefer public or unlisted for new apps. It is unrelated to the is_dev_app flag, which has different semantics.

chat — Interactive AI Chat

poe-tiles chat                    # Start interactive chat (default: Claude-Opus-4.6)
poe-tiles chat --model GPT-4o    # Use a different model

models — Model Management

poe-tiles models list             # List available LLM models

accounts — Connected Accounts

poe-tiles accounts list           # List linked OAuth accounts
poe-tiles accounts unlink <providerId>

upgrade — Self-Upgrade

Fetches the latest tarball manifest and reinstalls the global CLI. See Upgrading the CLI above for security and scope notes.

poe-tiles upgrade           # Upgrade to latest published tarball
poe-tiles upgrade --print   # Print the install command without running it

skills — SDK Skills

Install (or refresh) the SDK skills (tile-creator, synced-store) bundled with the currently-installed CLI. Use this to pull in newer skill content after upgrading the CLI, without re-scaffolding the app.

poe-tiles skills install                        # Writes to .claude/skills (default)
poe-tiles skills install --dir path/to/skills   # Custom target dir

Merges with existing skill directories — files at matching paths are overwritten, but user-added files outside the bundle are preserved. Each skill is written as <dir>/<skill-name>/. Note: a reference doc that was renamed or removed in a newer CLI will linger alongside the new version until you delete it manually.

Global Options

--json                           # Output as machine-readable JSON
--server <url>                   # Override the server URL (e.g. for local dev)
--version                        # Show version
--help                           # Show help

Environment Variables

Variable	Required	Description
POE_API_KEY	Yes	Your Poe API key (get one here)
POE_SERVER_URL	No	Server URL override (same as --server flag)

Using in scripts

All commands support --json for machine-readable output, making it easy to pipe into tools like jq:

# List app handles
poe-tiles apps list --json | jq '.[].handle'

# Sum point costs
poe-tiles auth points-history --json | jq '[.[] | .cost_points] | add'

# Get a specific app's bundle URL
poe-tiles apps get myuser/my-app --json | jq '.bundleUrl'

Local development

Point the CLI at a local server:

poe-tiles --server http://localhost:8787 apps list

Programmatic usage

The CLI package also exports a SlopPoeClient for use in scripts and tools:

import { SlopPoeClient, assertSuccess } from "@ai-app/poe-tiles-cli";

const client = new SlopPoeClient({ apiKey: process.env["POE_API_KEY"]! });

const result = await client.listApps();
assertSuccess(result); // throws on failure
for (const app of result.apps) {
  console.log(`${app.handle} (${app.id})`);
}