# BMCLI Installation and Deployment

## Supported packages

| Package | Intended systems | Runtime notes |
|---|---|---|
| `windows-x86` | Windows 10/11, x86 or x64 | 32-bit BMCLI and bundled MinGW BMAPI runtime |
| `linux-x86_64` | 64-bit x86 Linux with glibc | Bundled BMAPI shared library; libusb runtime required |
| `linux-aarch64` | 64-bit ARM Linux with glibc | Cross-built ARM64 package |
| `linux-armhf` | 32-bit ARM hard-float Linux with glibc | Cross-built ARMv7 package |

Run `bmcli doctor` after installation. A package being available for an
architecture does not replace validation on the target distribution and
hardware.

## Online installation

Windows PowerShell, current user:

```powershell
irm https://download.busmust.com/bmcli/install.ps1 | iex
```

Linux, current user:

```sh
curl -fsSL https://download.busmust.com/bmcli/install.sh | sh
```

The default Windows root is `%LOCALAPPDATA%\Programs\BMCLI`. The default Linux
root is `~/.local/share/bmcli`, with command and man-page links under
`~/.local/bin` and `~/.local/share/man/man1`.

## Offline installation

Extract the official archive without changing its contents. On Windows:

```powershell
powershell -ExecutionPolicy Bypass -File .\share\bmcli\packaging\install.ps1 `
  -PackagePath ..\bmcli-1.0.0-windows-x86.zip
```

On Linux, either run `./install.sh` inside an extracted package or install the
archive directly:

```sh
sh ./install.sh --package ./bmcli-1.0.0-linux-x86_64.tar.gz
```

## Update and version selection

`bmcli update --check` compares the installed version with the current stable
manifest and displays the verified changelist without downloading a binary.
`bmcli update` installs only when latest is newer; equal versions report
`up_to_date`. `bmcli update --version=X.Y.Z` selects an archived product version,
so the same mechanism is used for explicit upgrade and rollback.
`bmcli update --package=<archive>` performs an offline update through the bundled
installer. On Windows, BMCLI schedules the installer and exits before the active
executable is replaced.

Product versions use `X.Y.Z`. Bamboo build number and Git commit remain
separate diagnostic fields shown by `bmcli version --format=json` and do not
change the archive name.

## Uninstall

Windows:

```powershell
powershell -ExecutionPolicy Bypass -File `
  "$env:LOCALAPPDATA\Programs\BMCLI\share\bmcli\packaging\uninstall.ps1"
```

Linux:

```sh
sh ~/.local/share/bmcli/current/share/bmcli/packaging/uninstall.sh
```

The uninstallers remove BMCLI-owned command links, files, and installed BMCLI
skills. Pass `-KeepAI` on Windows or `--keep-ai` on Linux to retain the skills.
Linux udev configuration is retained by default; use `--remove-udev` only when
the rule is no longer needed by any BUSMUST software.

## Hardware prerequisites

BMCLI does not install Windows drivers. Install the BUSMUST WinUSB driver,
normally through BUSMASTER, before connecting from BMCLI. Linux users may run
the package installer with `--install-udev` and reconnect the device. This is
the only installer operation requiring `sudo`.

Initial Windows releases may be unsigned. Windows can show a browser download
warning, Microsoft Defender SmartScreen warning, or an unknown-publisher
prompt. Verify that the archive came from `download.busmust.com` and compare
its SHA-256 with the release manifest. Do not weaken PowerShell execution
policy or SmartScreen globally.

## AI integration

Installation runs `bmcli ai setup` by default. Codex-compatible agents use
`~/.agents/skills/bmcli`; Claude Code uses `~/.claude/skills/bmcli`. Run
`bmcli ai status --format=json` to verify both targets. The binary help is the
command contract; the skill must query `bmcli help <category> <action>
--format=json` before constructing nontrivial commands.

## Web automation service

Windows and Linux packages install the engineering console and OpenAPI contract
under `share/bmcli/web`. Open the required hardware channels, then start the
daemon-owned service:

```text
bmcli web start --listen=127.0.0.1:8080 --format=json
```

The console is at `http://127.0.0.1:8080/`; the exact client contract is
`/api/v1/openapi.json`, with runtime exposure metadata at
`/api/v1/operations`. The default service is local-only and CORS is disabled.
Any non-loopback listener must include `--token=<secret>` and the presence-only
`--allow-insecure-http` acknowledgement, and be restricted by the host firewall.
The current server is plain HTTP: the token authenticates but
does not encrypt the token, API payload, or bus data. Non-loopback use is limited
to a trusted isolated engineering network or an approved HTTPS reverse proxy;
never expose the listener directly to an untrusted LAN or the Internet.
`bmcli web stop` releases the listener without stopping a daemon that was
already running.

For an HTTPS-first Linux browser, keep BMCLI on loopback and use the packaged
Nginx profile:

```sh
sudo ~/.local/share/bmcli/current/share/bmcli/packaging/https/configure-nginx.sh \
  --certificate=/etc/ssl/certs/bmcli.crt \
  --private-key=/etc/ssl/private/bmcli.key \
  --server-name=localhost --install
```

Open `https://localhost:8443/` only after the certificate is trusted by the
browser. The release gate does not permit `curl -k`, browser certificate
bypasses, or disabling HTTPS-first policy.
