CLI Overview

The puc CLI gives you terminal-level access to the entire Upstreet platform -- generate assets, manage NPCs, chat with agents, work with containers, and more.

Terminal window showing the puc CLI with colorful output, listing NPCs and running a generation command, dark terminal theme

Installation

The CLI ships as part of the pu-client package:

npx puc --help

npm install -g pu-client
puc --help

git clone https://github.com/anthropics/pocketuniverse
cd pocketuniverse/packages/pu-client
pnpm install
pnpm cli --help

Authentication

puc login

This opens your browser for OAuth login. Paste the one-time code back into the terminal.

Or Use an API Key

Set your API key as an environment variable:

export PU_API_KEY="your-api-key-here"

The CLI reads from .env and .env.local in your current directory, or from the PU_API_KEY environment variable.

Logout

puc logout

Global Flags

Flag	Description
`--json` / `-j`	Output JSON instead of formatted text
`-h` / `--help`	Show help for any command
`--baseUrl <URL>`	Override the API host

Quick Examples

# Generate a character
puc character create -p "A cyberpunk hacker with neon tattoos" --smartPrompt

# List your NPCs
puc npc list

# Chat with an NPC
puc npc chat <npc-id>

# List your wiki projects
puc wiki list

# Open a container shell
puc container shell my-container

# Start the MCP server
puc mcp --port 8000

Interactive Mode

Running puc with no arguments starts an interactive chat session with a menu for selecting NPCs, managing generations, and more.

puc

Command Groups

Group	Description	Learn More
`generations`	Create, list, get, delete AI generations	Commands
`character`	Shortcut for character generation	Commands
`scene-image`	Shortcut for scene image generation	Commands
`scene360`	Shortcut for 360 scene generation	Commands
`scene-splat`	Shortcut for Gaussian splat generation	Commands
`model`	Shortcut for 3D model generation	Commands
`item`	Shortcut for item generation	Commands
`npc`	Manage NPCs (list, get, create, delete, chat)	Commands
`agents`	Manage agents (list, get, create, update, delete, chat, files)	Commands
`party`	Manage parties (list, get, create, delete, thread, chat)	Commands
`parties`	Party CRUD (list, get, create, update, delete)	Commands
`assets`	List and get asset binaries by type	Commands
`wiki`	Wiki projects and pages (go, list)	Commands
`container`	Cloud containers (ls, read, write, exec, shell, rsync)	Commands
`mcp`	Start an MCP server	Commands
`login` / `logout`	Authentication	Commands

Full Command Reference

Every command, flag, and example in detail.

Full Command Reference

On this page