Command Reference

Every puc command with full usage, flags, and examples.

Authentication

Opens your browser for OAuth login. Paste the one-time code to authenticate.

puc login

`puc logout`

Clears stored credentials.

puc logout

MCP

`puc mcp`

Start a Model Context Protocol server that exposes all PUClient tools.

puc mcp [--port <port>] [--host <host>]

Flag	Default	Description
`--port`	`8000`	Port to listen on
`--host`	`0.0.0.0`	Host to bind to

Clients must provide Authorization: Bearer <token> when connecting.

puc mcp --port 8000
UPSTREET_BASE_URL=https://api.example.com puc mcp

Generations

`puc generations create`

Create a generation using the generic interface.

puc generations create --type <type> [--input '{...}'] [--refType <t>] [--refId <id>]
puc generations create <type> [typed flags]

Common flags:

Flag	Description
`-p, --prompt <text>`	Text prompt
`-i, --imageUrl <url>`	Reference image URL
`--image <path>`	Local image file (uploaded automatically)
`--smartPrompt`	AI-enhanced prompt
`--refType <type>`	Reference asset type
`--refId <id>`	Reference asset ID

Examples:

puc generations create sceneImage -p "a castle at dusk" --smartPrompt
puc generations create --type character --input '{"prompt":"hero"}'

`puc generations get`

puc generations get <id> [--json]

`puc generations list`

puc generations list [--json]

`puc generations delete`

puc generations delete <id>

Typed Convenience Commands

Shortcuts that wrap generations create with type-specific flags.

`puc character create`

puc character create -p <prompt> [--imageUrl <url> | --image <path>] [--smartPrompt]

`puc scene-image create`

puc scene-image create [-p <prompt>] [--imageUrl <url> | --image <path>] [--smartPrompt]

`puc scene360 create`

puc scene360 create [-p <prompt>] [--imageUrl <url> | --image <path>] [--smartPrompt]

`puc scene-splat create`

puc scene-splat create [--splatUrl <url> | --splat <path>]

`puc model create`

puc model create [-p <prompt>] [--imageUrl <url> | --image <path>] [--smartPrompt]

`puc item create`

puc item create [-p <prompt>] [--imageUrl <url> | --image <path>] [--smartPrompt]

`puc character-render create`

puc character-render create --preview <url> --spritesheet <url> --rig <url>

NPC

`puc npc list`

puc npc list [-j]

`puc npc get`

puc npc get <id> [-j]

`puc npc create`

puc npc create --name <name> --src <source> [--refType <t>] [--refId <id>] [--voice <voiceId>]

`puc npc delete`

puc npc delete <id>

`puc npc chat`

Start a terminal chat session with an NPC.

puc npc chat <npcId> [<threadId>]

Agents

Alias for NPC management with additional capabilities.

`puc agents list`

puc agents list

`puc agents get`

puc agents get <id>

`puc agents create`

puc agents create --name <name> --src <source>

`puc agents update`

puc agents update <id> [--tools '{...}']

`puc agents delete`

puc agents delete <id>

`puc agents chat`

Interactive multi-agent chat.

puc agents chat [<agentId>] [<threadId>]

`puc agents files`

Manage agent file storage.

puc agents files list <agentId> [<path>]
puc agents files delete <agentId> <path>

Party

`puc party list`

puc party list [-j]

`puc party get`

puc party get <id> [-j]

`puc party create`

puc party create --name <name> [--members 'id1,id2,...']

`puc party delete`

puc party delete <id>

`puc party thread list`

puc party thread list <partyId> [-j]

`puc party thread`

Print messages from a party thread.

puc party thread <partyId> <threadId> [-j]

`puc party chat`

Start a chat session with a party.

puc party chat <partyId> [<threadId>]

Parties

CRUD operations for party management.

`puc parties list` / `get` / `create` / `update` / `delete`

puc parties list
puc parties get <id>
puc parties create --name <name> [--members 'id1,id2,...']
puc parties update <id> [--name <name>]
puc parties delete <id>

Assets

`puc assets list`

puc assets list --type <type> [--json]

`puc assets get`

puc assets get --type <type> <id> [--json]

Wiki

`puc wiki go`

Output a wiki page as markdown.

puc wiki go <pageIdentifier>

Page identifiers:

Format	Example
Path	`my-project/characters/Hero`
API URL	`http://localhost:3000/api/wiki/my-project/characters/Hero`
App URL	`http://localhost:3000/wiki/my-project/characters/Hero`

`puc wiki list`

puc wiki list [<projectName>] [-r, --raw]

Without a project name, lists all projects. With a project name, lists pages in that project.

Container

Cloud container management via sprites.dev.

`puc container list`

puc container list

`puc container remove`

puc container remove <name>

`puc container ls`

puc container ls <name> [args...]

`puc container read`

puc container read <name> <path>

`puc container write`

Reads from stdin and writes to a file in the container.

echo "hello" | puc container write <name> <path>

`puc container mkdir`

puc container mkdir <name> <path>

`puc container rm`

puc container rm <name> <path>

`puc container rsync`

Sync files between local filesystem and container.

puc container rsync <container>:path localpath
puc container rsync localpath <container>:path

`puc container exec`

Run a command inside a container.

puc container exec <name> <command> [args...]

`puc container shell`

Open an interactive bash shell in a container.

puc container shell <name>

Environment Variables

Variable	Description
`PU_API_KEY`	API key for authentication
`UPSTREET_BASE_URL`	Override API base URL

The CLI also reads .env and .env.local from the current working directory.

On this page