CLI reference

Repository commands are intentionally centralized in cargo xtask for generated System assets and source App packaging. Hardware UART tools each own one narrow operation.

`cargo xtask`

Command	Result
`cargo xtask build pi-agent`	Rebuild only the resident Pi Agent JavaScript bundle
`cargo xtask build view-sdk`	Rebuild only the shared PocketJS View resource pack
`cargo xtask package app <id> [credentials.json]`	Create `target/pocketapps/<id>.pocketapp`
`cargo xtask build esp32-sim`	Build the simulator with committed generated System assets
`cargo xtask run esp32-sim [args]`	Build and run the simulator with committed generated System assets
`cargo xtask snapshot esp32-sim`	Write deterministic screenshot to `artifacts/screenshots/`
`cargo xtask build esp32-p4`	Build ESP32-P4 release firmware with committed generated System assets
`cargo xtask build esp32-s3`	Build ESP32-S3 release firmware with committed generated System assets

Normal simulator and firmware commands do not inspect or modify a neighboring PocketJS checkout. POCKETJS_ROOT=/path/to/pocketjs applies only tocargo xtask build view-sdk; that command verifies the exact pinned PocketJS revision before replacing the generated resource pack.

Simulator arguments

cargo xtask run esp32-sim \
  --backend codex \
  --workspace target/esp32-workspace \
  --app pi-agent

xtask inserts the executable separator itself, so pass simulator flags directly. Supported arguments are:

--backend codex|openai|openrouter|anthropic|deepseek;
--model <id>;
--workspace <path>;
--viewport 720x1280|800x480|480x800 for View SDK and orientation testing;
--app pi-agent|files|apps|settings|keyboard|<installed-id>;
--prompt <text> and --tap x,y for deterministic scenarios;
--screenshot <path> on the simulator binary.

For the normal xtask form usecargo xtask run esp32-sim --backend codex. Do not add a second separator unless invoking Cargo directly.

UART helper boundary

The three Python commands share one raw 115200-baud POSIX UART layer intools/uart_io.py. It leaves DTR and RTS inactive when closing the port. Provisioning and the development bridge perform one explicit reset to enter their boot exchange;uart-install.py does not reset the board or change model configuration and only transfers one package to the on-device review flow.

Provision a physical board

python3 tools/uart-provision.py "$DEVICE_PORT" \
  --provider deepseek \
  --thinking-level high \
  --provision-wifi

Providers: openai, openrouter, anthropic, deepseek. --model overrides the provider default. Thinking level is high or xhigh. The command resets once to enter provisioning and waits for native storage confirmation. DeepSeek alone can read accountdeepseek-api-key from macOS Keychain service Pocket Pi Credentials; otherwise the tool prompts without echo.

Upload an App over UART

python3 tools/uart-install.py "$DEVICE_PORT" \
  target/pocketapps/exa.pocketapp

This transfers one package to a running device and waits for the upload acknowledgement; confirmation remains on-device.

Development-only model bridge

python3 tools/uart-model-bridge.py "$DEVICE_PORT" \
  --provider codex \
  --thinking-level high \
  --prompt "List your workspace." \
  --prompt-delay-seconds 3

Providers: codex or claude-code. Prompt delay accepts 0 to 120 seconds.

Flash and monitor

espflash list-ports
export DEVICE_PORT=/dev/cu.usbmodem...
espflash board-info --port "$DEVICE_PORT"

espflash flash --baud 921600 --port "$DEVICE_PORT" \
  --partition-table firmware/esp32-p4/partitions.csv \
  firmware/esp32-p4/target/riscv32imafc-esp-espidf/release/pocket-pi-p4

espflash monitor --port "$DEVICE_PORT"
espflash reset --port "$DEVICE_PORT" --non-interactive

Validation

cargo test --workspace
bun test apps/pi-agent/text.test.js
cargo clippy --workspace --all-targets -- -D warnings

Start here

Use the runtime

Build Apps

Understand the runtime

Security

Reference

Examples

Project