Metadata-Version: 2.5
Name: reterminal-cli
Version: 0.13.0
Summary: Agent and CLI for operating a Seeed Studio reTerminal edge device — provisioning, display, and I/O for the LCD/CM industrial terminal.
Project-URL: Homepage, https://github.com/agentculture/reterminal
Project-URL: Issues, https://github.com/agentculture/reterminal/issues
Author: AgentCulture
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Provides-Extra: graphics
Requires-Dist: cairosvg>=2.7; extra == 'graphics'
Requires-Dist: pillow>=10.1; extra == 'graphics'
Requires-Dist: pypdfium2>=4.30; extra == 'graphics'
Description-Content-Type: text/markdown

# reterminal

Agent and CLI for operating Seeed Studio reTerminal edge devices — the
reTerminal E (LAN, ESPHome push) and the reTerminal Sticky (ESPHome, an
always-on `board` service on the reterminal domain, enrolled-service push,
PDF pagination, and a touch dashboard that drives an AC through Sensibo) —
provisioning, display, and I/O for both.

## What you get

- **Device operation** — map devices to serial ports, query and flash SenseCraft
  firmware, render to the e-paper display, and sound the buzzer, all from the CLI.
- **The Sticky as a first-class device** — flash it via `firmware`, then run
  `reterminal board serve`: enrolled services push content over HTTP, PDFs
  page-turn by touch, and a touch dashboard drives an air conditioner through
  Sensibo, all authenticated end to end and reachable off-LAN through a
  `cloudflared` tunnel the `board tunnel` verbs wrap. See
  [`docs/esphome-reterminal-sticky.md`](docs/esphome-reterminal-sticky.md) and
  [`docs/delivery-map.md`](docs/delivery-map.md).
- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
  (`afi-cli`) — every command also speaks `--json`, and the runtime package has
  no third-party dependencies.
- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
  prompt file (`CLAUDE.md` for `backend: claude`).
- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
  PyPI Trusted Publishing wired into GitHub Actions.

## Quickstart

```bash
uv sync
uv run reterminal learn               # what the tool does + the command map (add --json)
uv run reterminal devices list        # local: device→serial-port mappings on this machine
uv run reterminal display set "hello" # needs a reachable reTerminal E (ESPHome firmware)
uv run reterminal whoami              # identity from culture.yaml
uv run pytest -n auto                 # run the test suite

# the board service (reTerminal Sticky, or E1001 enrolled as a panel):
uv run reterminal board serve --port 0     # foreground; --state-dir for a fixed home
uv run reterminal board token issue myservice --kind service
uv run reterminal board panel add sticky-1 --panel-profile sticky
uv run reterminal board push card --title "hello" --panels sticky-1

# the three demos (self-hosted by default — no hardware needed to run them):
bash scripts/demos/demo-1-service-push.sh
bash scripts/demos/demo-2-pdf-reader.sh
bash scripts/demos/demo-3-ac-dashboard.sh
```

`devices` is local; `firmware`, `display`, and `speaker` act on a connected
reTerminal E over LAN (USB-serial for `firmware flash`, the ESPHome HTTP API
for `display` / `speaker`). `board` is the Sticky/E1001 delivery service: it
runs independently of a connected device and talks to enrolled panels over
HTTP, device-initiated (the panel polls the board, not the reverse) — see
[`docs/esphome-reterminal-sticky.md`](docs/esphome-reterminal-sticky.md) for
the full delivery contract and [`docs/esphome-reterminal-e1001.md`](docs/esphome-reterminal-e1001.md)
for the E1001's LAN-push config.

## CLI

Operate a reTerminal E over LAN:

| Command | What it does |
|---------|--------------|
| `devices`: `record` / `list` | Record and list device→serial-port mappings (per-machine). |
| `firmware`: `list` / `flash` / `backup` | Query the SenseCraft firmware catalog, flash a reTerminal E or a Sticky (catalog image, or a local full image at `--offset 0x0` behind a mandatory verified-backup gate), and dump the whole 32 MB flash to a verified stock backup. |
| `display`: `set` / `show` / `image` / `card` / `cloud` / `svg` | Render text or graphics to the e-paper display (partial refresh — in place, no clear-flash; full clear every Nth update). |
| `speaker`: `beep` | Sound the buzzer. |

Run the board service (Sticky and/or E1001 as enrolled panels):

| Command | What it does |
|---------|--------------|
| `board serve` | Run the board service in the foreground (stdlib `http.server`, no runtime dependency). |
| `board token`: `issue` / `list` / `revoke` | Bearer tokens every board endpoint requires — one exchange enrolls a service or a panel. |
| `board panel`: `add` / `list` / `remove` | Enroll panels: profile (`e1001`/`sticky`) and wake interval. |
| `board push`: `card` / `cloud` / `text` / `png` | Render and push content to enrolled panels — the CLI mirror of `POST /v1/push`. |
| `board pdf`: `load` / `status` / `clear` / `turn` | Load a PDF, rasterized host-side; touch/button page-turns it. |
| `board dashboard`: `apply` / `show` | A rendered tap dashboard, hit-tested server-side, driving an AC through Sensibo. |
| `board audit` | The recent dashboard command attempts and their outcomes. |
| `board reassert` | Force a panel to re-fetch the board's content, no new bytes. |
| `board actions`: `list` / `set` / `remove` | Map a reported event type (touch/wake/button) to a local command (host-only config, no HTTP write route). |
| `board tunnel`: `open` / `close` / `status` | Expose the board off-LAN by wrapping `cloudflared`. |
| `board ui-url` | Print the packaged web UI's ready-to-open entry URL for a token. |

Every board endpoint requires a bearer token, `/health` included — see
`reterminal explain board`. Demo scripts + fixtures live under
[`scripts/demos/`](scripts/demos/): `demo-1-service-push.sh`,
`demo-2-pdf-reader.sh`, `demo-3-ac-dashboard.sh` each self-host a board and
print `MEASURED:` timings against the spec's battery-first targets, or (with
`BOARD_URL`/`PANEL_ID`/`PANEL_TOKEN`/`SERVICE_TOKEN` set) run the same script
against real hardware.

Introspection and identity:

| Command | What it does |
|---------|--------------|
| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
| `learn` | Print a structured self-teaching prompt. |
| `explain <path>` | Markdown docs for any noun/verb path. |
| `overview` | Read-only descriptive snapshot of the agent. |
| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
| `cli overview` | Describe the CLI surface itself. |

Every command supports `--json`. Each noun group has its own `overview`
(`reterminal display overview`). Results go to stdout, errors/diagnostics to
stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
error, `3+` reserved.

## Fork it for another agent

reterminal began as the `culture-agent-template` scaffold, so it doubles as a
starting point for a new AgentCulture mesh agent. To repurpose it:

1. Rename the package `reterminal/` and the `reterminal`
   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
   ~100 places, so list every occurrence first — see the `git grep` discovery
   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
2. Edit `culture.yaml` with your `suffix` and `backend`.
3. Rewrite `CLAUDE.md` for your agent and run `/init`.
4. Re-vendor only the skills you need from guildmaster (see
   [`docs/skill-sources.md`](docs/skill-sources.md)).

See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
the `cicd` PR lane, deploy setup).

## License

MIT — see [`LICENSE`](LICENSE).
