# Board Connect

Board Connect lets you install, launch, and inspect your apps on Board over your local network. No physical connection is required, and it works the same on macOS, Linux, and Windows.

There are two ways to use it:

- **Web UI:** A graphical interface Board serves to your browser. Best for installing and managing apps by hand when you are near Board.
- **`board-connect` CLI:** The command-line tool for terminals, coding agents, and CI.

Both connect to Board and need a one-time pairing to authorize your computer.

## Web UI

Every Board serves the web UI at `http://<device>:8843/`. From a browser on the same network you can:

- install apps (`.apk` or `.webapp.zip`) by drag-and-drop or file picker,
- launch, stop, and uninstall them,
- stream live logs, filtered by tag and level,
- capture and download screenshots.

**Open it:**

1. On Board, open **Settings > System > Pair a computer > Show pairing code**. Board’s web address will be listed.
2. Browse to `http://<that-address>:8843/` then enter the six-digit code in the browser.

That pairs your browser and unlocks the interface.

**Restrictions:**

- Your computer must be on the same network as Board. There is no remote access.
- It is a hands-on tool. For scripting, CI, or coding agents, use the CLI detailed below.

## CLI

### Install

**macOS and Linux:**

```
curl -fsSL https://dev.board.fun/connect/install | sh
```

**Windows (PowerShell):**

```
irm https://dev.board.fun/connect/install.ps1 | iex
```

The installer drops a single binary at `~/.local/bin/board-connect` (on Windows, `%USERPROFILE%\.local\bin\board-connect.exe`). Add that directory to your `PATH` if it isn’t already, then verify:

```
board-connect --version
```

> **macOS note**: installing via `curl` keeps Gatekeeper from quarantining the binary, so it runs without a security prompt. If you obtain it another way (for example, by downloading it from the [Board Developer Portal](https://dev.board.fun/login)), clear the quarantine attribute first: `xattr -d com.apple.quarantine ~/.local/bin/board-connect`.

### Pair

Pairing authorizes your machine to manage a Board, issues a bearer token that later commands reuse, and saves that Board as your default, so once you have paired, no command needs an address. You pair a given Board once.

```
board-connect pair   # discover a Board, then tap Approve on Board
```

Board shows an approval prompt on screen (“Allow this client to manage your Board?”); tap **Approve** and the command completes. From then on, every command reuses the token and the saved default with no further interaction.

Don’t know the address? Run `board-connect ls` to discover Boards on your network. To target a different Board for a single command, pass `-b, --board <addr>` (or set `BOARD_HOST`).

> `pair` is idempotent: if the saved token still works, it is a no-op that refreshes the default. Pass `--force` to mint a fresh token. The token lives at `~/.config/board-connect/tokens.json`; override the location with `XDG_CONFIG_HOME`, or supply one out of band with the `BOARD_TOKEN` environment variable.

### Deploy

Once you have paired, install an app and launch it in a single step, with no address on the command:

```
board-connect install ./dist/MyGame.webapp.zip --launch
```

This works for both native Android apps and web apps. Pass an `.apk` or a `.webapp.zip` and the CLI detects the bundle type from its contents, so the same command covers either kind. Board validates the bundle, installs it, and (with `--launch`) brings it to the foreground.

```
$ board-connect install ./dist/MyGame.webapp.zip --launch
Installed MyGame (appId 7f3c1e90-2b4a-4d11-9c0e-8a51d2f6b4aa)
Launched
```

### Common commands

App commands take a single `<id>`, which is either an APK package name or a web-app `appId`; the CLI resolves which it is. None of these need a Board address once you have paired.

| Command | Description |
| --- | --- |
| `board-connect ls` | Discover Boards on your network (name / model / serial / ipv4 / transport) |
| `board-connect use <addr>` | Set the default Board (address, or name/serial via discovery) |
| `board-connect open [board]` | Open a Board’s web UI in your browser (no argument discovers) |
| `board-connect pair` | Pair with a Board (tap **Approve** on Board); `--code`, `--force` |
| `board-connect status` | Check device readiness |
| `board-connect version` | Show Board OS version (distinct from the CLI’s `--version`) |
| `board-connect capabilities` | Show protocol version and feature tags (alias: `caps`) |
| `board-connect apps` | List installed dev apps (APKs and web apps) |
| `board-connect install <file>` | Install an `.apk` or `.webapp.zip` (type auto-detected); add `--launch` |
| `board-connect launch <id>` | Launch an installed app by id |
| `board-connect stop <id>` | Stop a running app |
| `board-connect remove <id>` | Uninstall an app by id (confirms unless `--yes`) |
| `board-connect cleanup` | Uninstall all dev-managed apps (`--yes` to skip the confirm) |
| `board-connect logs <id>` | Dump recent logs (`--tag`, `--level`); add `--follow` to stream live until Ctrl-C |
| `board-connect screenshot` | Capture the screen (`--out file.png`) |

Read commands accept `--json` for machine-readable output. `-y, --yes` skips destructive-action confirmations, `-q, --quiet` suppresses informational notices like `Using <board>`, and `--follow` streams logs live for APKs (web apps fall back to a one-shot dump).

## Reference

For the full command set, run `board-connect --help` (or `board-connect <command> --help`). Every command is a thin wrapper over Board’s HTTP API; the [Board Connect API reference](https://docs.dev.board.fun/tools/board-connect-api) documents the complete surface: discovery, pairing, app lifecycle, logs, screenshots, and paired-client management.