CLI reference

pocket-studio makes, sends and publishes Pocket Studio games from a terminal. The setup command on the workbench installs it (Set up your computer); it runs on Bun 1.3 or newer. pocket-studio --help prints the list below, and pocket-studio --version its version.

Run link, new, create, remix, register and the account commands anywhere. Run the others inside a project: the directory that holds .pocket-studio.json, or one below it.

#Commands

#Your account

#link

pocket-studio link K7QD-9M4X

Linked this machine to https://studio.pocket.nexus as docs-writer

Links this computer to the account that made the code. The code comes from the room: the agent card on the workbench and Remix on a game's card write one. It works once and for 15 minutes. A computer stays linked until unlink.

#whoami

Prints the linked account, docs-writer at https://studio.pocket.nexus, or fails when there is none:

This machine is not linked to https://studio.pocket.nexus.
Get a link code from the room (click the Claude or Codex figure), then run: pocket-studio link <CODE>

#handle

pocket-studio handle prints your handle; pocket-studio handle docs-writer chooses another. Your published games say By and the handle.

#unlink

Forgets the link to the server on this computer.

#Making a game

#new

pocket-studio new --device psp --title "Moon Lander" --agent claude

Started "Moon Lander" for PSP as docs-writer
Created ./moon-lander from the snack-snake starter
Build 1 is on the PSP (.pocket/studio/out/psp/moon-lander.js, 514 KiB)

Creates a project from a starter game, opens a session for the device in your room, and compiles and sends the first build. The directory must be absent or empty. Inside a project, --dir . gives the game a session on another device and keeps its files.

#create

pocket-studio create PINE-QWJ6

Runs the command the room writes under New game: links this computer with the pairing code, creates the project, sends the first build and starts a coding agent in it. A pairing code works once and for 15 minutes. If the project could not be written after the code was used, the same command run again within a day picks the link up.

#continue

Starts the coding agent again in a game's project: the one in this directory, or the game the room names by its id.

#title

pocket-studio title "Moon Lander" --tagline "Land on three pads before the fuel runs out."

The game is "Moon Lander" in the room.
Its card says: Land on three pads before the fuel runs out.
Its title screen is drawn by the project: change the title there too.

Writes the title into studio.json, every pocket*.json and the // @title line, and tells the room at once. A title is 1 to 60 characters and a tagline at most 80; a longer one is refused and nothing is written.

#dev

Rebuilds the game on every change you save and sends each build that differs from the last, until you press Ctrl-C.

Watching . for changes. Press Ctrl-C to stop.

#push

Compiles the game for the session's device and sends the build. A build that fails prints its errors with file and line and sends nothing. The title, tagline and cover colours of studio.json go with it when they changed. No change since build 1 means the compiled game is the one the room has.

#shot

pocket-studio shot --do "wait 1; shot title; press CIRCLE; wait 0.5; shot play"

Builds the game and runs it on this computer with no screen, on the WebAssembly core the room's device runs, and writes a PNG for each shot step into .pocket/studio/shots/. It sends nothing to the room and needs no network. Under each picture it prints every text on screen with its box, and a layout: line that says whether each text fits its box. The same steps give the same pictures every time.

Steps, separated by `;`:
  wait <time>                         let the game run
  press <BUTTON>                      down for 1 frame, then up for 1 frame
  hold <BUTTON> <time>                down that long, then up for 1 frame
  down <BUTTON>                       press it and keep it down through the steps that follow, a shot among them
  up <BUTTON>                         let go of a button that `down` holds
  until "<text>" [time]               run frame by frame until a text on screen contains it; the run fails when the time passes first (default 10 seconds of game time)
  tap <x> <y> [time]                  touch the screen at a point, in the touch screen's logical pixels (default 1 frame)
  swipe <x0> <y0> <x1> <y1> [time]    drag a finger from one point to another (default 0.2, at least 2 frames)
  shot [name]                         write a PNG and print what is on screen
Time: seconds (`0.5`) or whole frames with an f (`30f`). Every device runs 60 frames a second. Seconds times 60 is rounded to the nearest frame, a half up, and is at least 1 frame: `wait 0.7167` is 43 frames.
Buttons: SELECT, START, UP, RIGHT, DOWN, LEFT, L, R, TRIANGLE, CIRCLE, CROSS, SQUARE. On the 3DS, A, B, X and Y too.
Several buttons: `press`, `hold`, `down` and `up` take buttons joined with +, as in `press L+R`. `down` adds to what is held, so `down LEFT; down CROSS` holds both.
Frames: the game sees a button go down on the first frame it is held after a frame it was up, so `press` takes 2 frames and `hold CROSS 90f` takes 91. `down` and `up` take 1 frame each, the frame the game sees the change on: `press X` is `down X; up X`.
`until` reads the texts a shot lists, with upper and lower case as written. Put the text in quotes when it has a space: `until 'GAME OVER' 20`.
Pictures: .pocket/studio/shots/<name>.png for the session's device, .pocket/studio/shots/<device>/<name>.png for another one under --device. A run replaces the pictures of the directory it writes and of no other.

#status

"Moon Lander" on PSP
phase: published
build: 1
message: Published
address: https://moon.studio.pocket.nexus
page: https://studio.pocket.nexus/games/moon
listing: none

Prints the session's phase, its build and its last message, then the game's address, page, listing and packages when it has them. For a registered game it prints what the game has published.

#Publishing

#publish

Published "Moon Lander". Share: https://studio.pocket.nexus/studio/?app=a8ja3s2exefnv
Address: https://moon.studio.pocket.nexus

Makes the game public and prints its share link and address. Publishing and sharing says how an address is chosen.

#cover

Sets the picture on the game's case, its card and Pocket TV: a PNG of 64 to 2048 pixels on each side, at most 2 MiB.

#downloads

pocket-studio downloads on lets members download the game's packages, and off stops it.

Downloads are on for "Moon Lander". It has no package yet.

#listing

Sets what the game's page shows from a directory with listing.json: clips, pictures, a description and a share picture. Games built elsewhere has every rule.

#delete

"Moon Lander" would be deleted from https://studio.pocket.nexus for good:
  address: https://moon.studio.pocket.nexus
  builds: psp
Nothing was deleted. Run it again with --yes to delete it.

#Remixing

#remix

pocket-studio remix a8ja3s2exefnv --agent claude

Starts a game of your own from a copy of a published game, named by its id, its share link or its address. A game made in Pocket Studio becomes a project with a session; a game built elsewhere is cloned from its repository with git. See Remix.

#repository

Names the public repository of a game built outside Pocket Studio, so it can be remixed once it is published; --remove takes it off.

#Games built elsewhere

#register

Registers a game built with its own tools, and links the directory to it. See Games built elsewhere.

#site

Deploys a directory of static files as the game's web build, at its address. For games Pocket Nexus verified.

#package

Uploaded moon.3dsx (4 KB), version 0.1.0 for 3ds.
Members can download it from the game's page.

Uploads an installation package for one device. See Packages.

#Setup

#agent

pocket-studio agent install claude installs the Pocket Studio plugin into Claude Code with its own plugin commands (codex for Codex); agent status says where each agent has it; agent remove takes it out. The setup command runs agent install for you.

claude  pocket-studio@pocket-nexus 0.1.0, enabled, from ~/.pocket-studio/plugins/pocket-studio
codex   no plugin. Run: pocket-studio agent install codex

#agents

Lists the coding agents found on PATH.

#update

Downloads the kit the Studio serves now and installs it as the setup command does, then gives each agent that has the plugin the new one. Once a day, after a command that talks to the Studio, an installed pocket-studio checks whether a newer kit is out and says A newer Pocket Studio is out. Run: pocket-studio update.

#The server

Every command talks to https://studio.pocket.nexus unless told otherwise:

#Files

#Environment

#Exit codes and errors

A command ends with 0 when it did what it was asked and 1 when it did not, with the reason on the error output. delete without --yes, a shot step that fails and a build with errors end with 1.