dreamboard

Dreamboard CLI for working with Dreamboard games from your own editor/tooling.

Dreamboard is built to take you from napkin sketch to playable prototype without the paper cuts:

• Describe the game you want to make.
• Generate the rules, components, and scaffolding.
• Playtest instantly with a frictionless lobby and live iteration loops.

The platform’s core promise is the same one described on the landing page: digital prototyping for everyone, with AI helping you move from idea to playable faster.

Install

Published npm package:

npm install -g dreamboard

The published CLI targets Node 20+.

Why Dreamboard

• Describe: start from theme, mechanics, and player experience instead of boilerplate setup.
• Generate: Dreamboard handles the sandbox primitives like turns, hands, and structured scaffolding.
• Playtest: share a live prototype instead of printing fresh paper every time a rule changes.
• Iterate live: keep testing momentum by changing values and flows without resetting the whole process.

Authentication

Use browser login:

dreamboard login

The published CLI stores your refreshable session in:

~/.dreamboard/config.json

That stored session includes the refresh token the CLI needs to renew access automatically. Direct JWT injection is intentionally not part of the published CLI flow.

Source Checkout Setup

For local source-checkout development, install workspace dependencies with pnpm and keep Bun available for local embedded-harness workflows:

pnpm install

Playwright (for dreamboard run):

npx playwright install

Commands

Create a new game:

dreamboard new my-game --description "A trick-taking card game"

Clone an existing game:

dreamboard clone my-game

Sync local authored changes and regenerate scaffolded files:

dreamboard sync
dreamboard sync --update-sdk

If the remote has advanced unexpectedly, reconcile authored changes explicitly with:

dreamboard pull

Compile the current authored head:

dreamboard compile
dreamboard compile --skip-local-check

Inspect local vs remote state:

dreamboard status
dreamboard status --json

Run the game locally (server-compiled UI):

dreamboard run
dreamboard run --players 4
dreamboard run --seed 1337
dreamboard run --new-session

If no successful compile exists for the current authored state yet, dreamboard run will ask you to run dreamboard compile first. By default, the CLI uses manifest.json's playerConfig.minPlayers to decide how many seats to create.

dreamboard run now defaults to a wait-and-observe loop when no scenario is provided:

1. Reuse the previous active session (--resume defaults to true) unless --new-session is set.
2. Subscribe to session SSE events.
3. Exit when YOUR_TURN (default --until) or GAME_ENDED is received.
4. Persist artifacts in .dreamboard/run/:
   • session.json
   • events.ndjson
   • latest-your-turn.json
   • last-run-summary.json

dreamboard run is deterministic-by-default for new sessions: if --seed is not provided, it uses 1337.

Useful flags:

• --until YOUR_TURN|GAME_ENDED|ANY
• --observe-events turns|all (default turns; persist YOUR_TURN and ACTION_REJECTED messages)
• --seed <int> (deterministic RNG seed for new sessions, default 1337)
• --timeout-ms <ms>
• --max-events <count>
• --screenshot (capture one Playwright screenshot for the selected run session)
• --output <path>
• --delay <ms>
• --width <px>
• --height <px>
• --scenario-driver api|ui (default api)

Playwright launch is now optional:

1. It is launched when --scenario-driver ui is used.
2. It is launched when --screenshot is used.
3. Default API scenarios (--scenario with --scenario-driver api) do not require Playwright.
4. Pure observe runs (dreamboard run without scenario/screenshot) do not require a browser session.

Scenario Files

dreamboard run --scenario <file> supports scenario JSON (API driver by default):

{
  "steps": [
    {
      "playerId": "player-1",
      "actionType": "playCard",
      "parameters": { "cardId": "hearts-7" },
      "turns": 1
    },
    {
      "playerId": "player-1",
      "actionType": "endTurn",
      "parameters": {},
      "turns": 1
    }
  ]
}

playerId is required on every scenario step. The CLI executes all steps in order per invocation:

dreamboard run
dreamboard run --scenario path/to/scenario.json
dreamboard run --scenario path/to/scenario.json --scenario-driver ui

If there is no current .dreamboard/run/latest-your-turn.json for the active session (for example with --new-session), dreamboard run --scenario ... first observes SSE until it receives the initial YOUR_TURN, then starts executing scenario steps.

API-driven scenarios are strict per step: after each submitAction, the CLI waits for either ACTION_EXECUTED or ACTION_REJECTED. On rejection, it stops immediately with stopReason=scenario_rejected.

Screenshots are saved to .dreamboard/screenshots/ by default. The CLI captures the same session selected by --resume / --new-session.

To capture a screenshot during observe or scenario runs:

dreamboard run --screenshot
dreamboard run --scenario path/to/scenario.json --screenshot
dreamboard run --screenshot --output ./shot.png --delay 1500 --width 1440 --height 900

Notes

• Project state lives in .dreamboard/project.json.
• Snapshots for status are stored in .dreamboard/snapshot.json.
• Published/public CLI installs target Node 20+ and support remote workflows.
• Published/public CLI builds are production-only; they do not support environment overrides or direct JWT injection.
• Local embedded-harness testing remains Bun-only and requires a source checkout with local backend support.
• Internal source-checkout builds may expose extra auth and environment helpers, but those are not part of the published CLI contract.

Skill Source

• Public skill source lives under skills/dreamboard/.
• dreamboard new installs the bundled skill into .agents/skills/dreamboard/ in the generated game project.
• The Node helper script for run-artifact inspection is .agents/skills/dreamboard/scripts/events-extract.mjs.
• Public GitHub repo for the CLI is dreamboard-games/dreamboard-cli.