# hil-cli — Package Manager Command Reference

`hil-cli` is the HIL-OS package manager. It scaffolds projects, manages macro
packages, runs/simulates/builds scripts, and generates CRUMB circuit files.

```
hil-cli <command> [options]
```

Run `hil-cli` with no arguments (or `hil-cli help`) to see the banner and help.
Exit codes: `0` success, `1` error, `2` unknown command.

## Project scaffolding

### `init <name> [--template <tpl>]` / `new <name> [--template <tpl>]`

Creates a project directory. `init` and `new` are synonyms.

```powershell
hil-cli init demo --template basic
hil-cli new  blinky --template blink
```

Available templates:

| Template | Contents |
|----------|----------|
| `basic`  | Entry script + `lib/cyber.hil` macro library |
| `blink`  | Minimal blink loop on pin 13 |
| `events` | Event-driven sensor watchdog (`ON-EVENT`/`ON-CHANGE`) |
| `pid`    | Closed-loop PID control project |
| `crumb`  | Simulation project for CRUMB (LISP → `.cru`) |

Every project gets `.vscode/tasks.json` (Build Hex, Inject, Simulate in CRUMB,
and a default "Build & Run" task so **F5** compiles and injects, plus a Stop
task), `.vscode/settings.json`, `hil.json` manifest, and `README.md`.

### `list`

Lists the available project templates.

## Package management

### `add <pkg>...`

Installs a macro package into `lib/` and records it in `hil.json`:

```powershell
hil-cli add cyber
hil-cli add pid
```

Available packages: `cyber` (`cyber.hil`), `pid` (`pid.hil`).

### `install`

Restores every package listed in `hil.json` (run after cloning a project or
after editing the manifest by hand).

### `list-pkgs`

Lists the available macro packages.

## Running scripts

### `run [file]`

Starts `hil-orchestrator` interactively and injects the script after the
monitor boots. Relays your keystrokes to the monitor REPL. Typing `exit` or
`quit` severs the link. Use `HIL_PORT` / `HIL_BAUD` env vars to control the
link (default `auto` / `9600`). The script defaults to `src/main.hil` (or
`hil.json` `main`).

### `simulate [file]`

Runs the script headlessly through the IPC mode (`-ipc -port none`). No
hardware and no serial port required. Prints the JSON IPC stream and all
`LOG` output.

### `build [file]`

Compiles the script to an Intel HEX artifact next to the script
(`-build` flag on the orchestrator).

### `send [file]`

Injects the script into an already-running monitor over TCP `localhost:9000`.

### `stop`

Sends the halt signal to the running monitor.

### `flash [file]`

Clears autopilot memory, streams the script, and commits it as boot logic
(`A C 0 0 0` → `run <file>` → `A S 1 0 0`).

## CRUMB simulation

### `crumb [file] [--out <path>] [--open] [--strict] [--crumb-dir <dir>]`

Transpiles a HIL script to Arduino C and injects it into a `.cru` Nano circuit
(cloned from the built-in CRUMB Nano design). Output defaults to
`simulation/<scriptname>.cru`.

| Flag | Meaning |
|------|---------|
| `--out <path>` | Override the output `.cru` path. |
| `--open` | Launch CRUMBWPF.exe with the generated circuit. |
| `--strict` | Fail if the transpiler produced any warnings. |
| `--crumb-dir <dir>` | CRUMB install directory override. |

CRUMB is located via `--crumb-dir`, then `HIL_CRUMB_DIR`, then the default
dev path. The generated `.cru` is validated for XML well-formedness and the
sketch is injected into the Nano component's first `<xsd:string>` element.

**Buzzer note:** Use a **passive buzzer** on pin D11. The transpiler generates
`tone()` calls — active buzzers just set the pin HIGH silently.

See [CRUMB-SIMULATION.md](CRUMB-SIMULATION.md).

### `crumb-open [file]`

Opens a `.cru` in CRUMB. With no file, opens the most recently generated
`.cru` in `./simulation`.

## Firmware (real hardware)

### `firmware info`

Shows available build tools (TinyGo, avr-gcc, avrdude, arduino-cli) and Arduino
Uno specs. Tells you what to install.

### `firmware build [--board uno|nano|mega] [--out path]`

Compiles `firmware.go` to a `.hex` file. Requires TinyGo.

```powershell
hil-cli firmware build --board uno
hil-cli firmware build --board nano --out my-firmware.hex
```

### `firmware flash [--board uno|nano|mega] [--port COM3] [--hex path]`

Flashes the firmware to a real Arduino. Uses TinyGo flash if available, falls
back to avrdude. Auto-detects serial port if not specified.

```powershell
hil-cli firmware flash --board uno --port COM3
hil-cli firmware flash --board nano
```

**Arduino Uno (ATmega328P):** 32KB flash, 2KB SRAM, 16MHz clock.

**Requirements:** Install TinyGo (https://tinygo.org) or Arduino IDE
(bundles avr-gcc + avrdude).

## VS Code Integration

### `install-vscode`

Packages and installs the HIL LISP extension for VS Code. Provides syntax
highlighting, 20+ code snippets, and right-click actions (Run / Simulate /
Transpile to CRUMB) for `.hil` and `.lisp` files.

```powershell
hil-cli install-vscode
```

Requires: `code` CLI on PATH, `npm` for packaging.

## Serial Port Scanner

### `ports`

Scans all serial ports on the system and presents an interactive selection menu.
Shows port availability (available / in use) and lets you pick a port by number.

```powershell
hil-cli ports
```

Output:
```
Scanning serial ports...

  NUM     PORT          STATUS        DESCRIPTION
  -------------------------------------------------------
  [1]     COM1          available     USB Serial
  [2]     COM3          available     USB Serial

Select port number (or Enter to cancel): 2

[OK] Selected: COM3 (USB Serial)

Use this port with:
  hil-cli run --port COM3
  hil-cli firmware flash --port COM3
```

## Diagnostics

### `doctor`

Checks: Go toolchain, Node.js, `hil-orchestrator.exe`, the Node wrapper,
CRUMB installation, and runs self-tests for the LISP→C transpiler and the
`.cru` generator. Exits non-zero if any check fails.

## Environment variables

| Variable | Used by | Meaning |
|----------|---------|---------|
| `HIL_ORCHESTRATOR` | run/simulate/build/send/stop/flash | Path to `hil-orchestrator.exe` |
| `HIL_PORT` | run | Serial port (default `auto`) |
| `HIL_BAUD` | run | Baud rate (default `9600`) |
| `HIL_CRUMB_DIR` | crumb/crumb-open | CRUMB installation directory |
| `PATH` | firmware | TinyGo, avr-gcc, avrdude, arduino-cli must be on PATH |
