# One command, your local game

Run twf dev from a repository and choose the CLI with direnv.

## Start from the repository

```sh
twf dev
twf dev --port 4310
```

The CLI finds the nearest `boardengine.json`, using its `entry`, optional named `export`, and `assets` directory. Discovery stops at a package or Git repository boundary. Without a config, it uses that package's `src/game.ts`. Invalid configuration fails explicitly.

```sh
twf dev --config configs/local.json
twf dev src/another-game.ts --export game
```

Paths inside a config are relative to that JSON file. An explicit module is relative to the current directory. Choose a config or a module, not both. Local development requires no platform login.

## Put the repository's CLI on PATH

New projects include `.envrc`. With direnv installed and its shell hook enabled, approve that file once:

```sh
pnpm install
direnv allow
twf --version
twf dev
```

The file adds `node_modules/.bin` to PATH. It uses the CLI installed by this repository's lockfile, including when you enter a child directory. It does not install packages or change versions when you enter the directory. Without direnv, `pnpm exec twf dev` does the same job.

## Work on the latest engine source

The engine repository has its own `.envrc`, which exposes `scripts/bin/twf`. That shim runs the CLI TypeScript source in the current checkout, so CLI edits take effect on the next invocation without building or reinstalling a global package.

To use that source CLI from an independent game repository, add this to the game's ignored `.envrc.local`:

```sh
PATH_add /absolute/path/to/boardengine/scripts/bin
```

Install dependencies in the engine checkout first. Run `direnv allow` after creating the override, then check `command -v twf`. This selects the source CLI while the game continues to load its own installed SDK. Testing an unreleased SDK is a separate, deliberate dependency change; it can be installed from an SDK tarball produced by `pnpm release:pack` in the engine checkout.

## Upgrade the published CLI deliberately

```sh
pnpm add -D --save-exact @tabletopwithfriends/cli@latest
twf --version
twf dev
```

Review and commit the package and lockfile changes. `latest` selects the newest published CLI when you run the install command; the saved dependency becomes exact. For an older compatibility line, use a tag such as `@tabletopwithfriends/cli@sdk-0.1`, or an exact release number. The SDK remains pinned independently. Unsupported host APIs fail with instructions to use the matching CLI.