<!-- Generated by apps/dreamboard-cli/scripts/sync-skill-docs.ts. -->
<!-- Source: docs/reference/cli.mdx -->

# CLI

Reference for Dreamboard CLI workflows and commands.

Dreamboard CLI manages the authored workspace loop: authenticate, create or
clone a game, sync authored changes, compile, run, and test.

## Responsibility

Use the CLI for:

- authenticating the current machine
- creating or cloning game workspaces
- syncing authored files to the remote authoring head
- compiling the current authored head
- inspecting local versus remote state
- pulling remote authored changes into the workspace
- starting or observing playable sessions
- generating and running reducer-native tests

## Install targets

Use the published package for normal game work:

```bash
npm install -g dreamboard
dreamboard login
```

## Command flow

Use this sequence for the normal authored loop:

1. `dreamboard login`
2. `dreamboard new ...` or `dreamboard clone ...`
3. edit `rule.md`, `manifest.json`, and authored source files
4. `dreamboard sync`
5. `dreamboard compile`
6. `dreamboard run` or `dreamboard start`
7. `dreamboard test generate`
8. `dreamboard test run`

When the remote authored head moves first, run `dreamboard pull` before the
next sync or compile. Use `dreamboard status` to decide whether the workspace is
ahead, behind, or diverged.

## Workspace commands

| Command | Use it for |
| --- | --- |
| `dreamboard login` | Open browser login and store a refreshable session |
| `dreamboard new <slug> --description "..."` | Create a new game and scaffold a local workspace |
| `dreamboard clone <slug>` | Clone an existing game into a new local workspace |
| `dreamboard sync` | Upload authored changes and refresh scaffolded files |
| `dreamboard compile` | Compile the current remote authored head |
| `dreamboard status` | Compare local authored and compile state with remote |
| `dreamboard pull` | Reconcile remote authored changes into the workspace |

```bash
dreamboard new race-to-ten --description "A tiny scoring game"
dreamboard sync
dreamboard compile
dreamboard status --json
```

## Session commands

Use session commands after you have a successful compile for the current
authored head.

| Command | Use it for |
| --- | --- |
| `dreamboard run` | Start or resume a playable session and observe it from the CLI |
| `dreamboard start` | Start a fresh session and open it in the browser |

```bash
dreamboard run
dreamboard run --players 4 --seed 1337
dreamboard run --scenario path/to/scenario.json
dreamboard start --players 2
```

`dreamboard run` reuses the previous active session by default. Use
`--new-session` when you want a fresh session instead.

## Test commands

Use the scaffolded reducer-native test workspace for repeatable game assertions.

```bash
dreamboard test generate
dreamboard test run
dreamboard test run --scenario test/scenarios/player-two-wins.scenario.ts
```

## Start local server
```bash
dreamboard dev
```

See [Testing](./testing.md) for the scenario and base-file format.
