# `plesty-bench`

The client for a bench you are not sitting at. It sends a `plesty-server`
command to the bench's **agent** and prints what the bench answers — so every
[`plesty-server` command](plesty-server.md) works from your own machine, with
nothing new to learn. It is small (`pyzmq` and `click`) and brings no Qt and
nothing of the bench application.

The bench has to be serving its agent: *Server ▸ Start agent* in the console,
or `plesty-server fleet run --agent` on a bench without a window. Setting that
up is [Work from another machine](../usage/remote.md).

## Install

```bash
uv tool install plesty-bench              # the client
uv tool install "plesty-bench[control]"   # … and the control panels, which need Qt
```

## Usage

```bash
plesty-bench [-b HOST[:PORT]] [--token TOKEN] [--timeout 60] COMMAND …
```

| Option | Means |
|---|---|
| `-b`, `--bench HOST[:PORT]` | The bench. Port 5550 unless given. `PLESTY_BENCH` sets a default. |
| `--token TOKEN` | The agent's shared secret — the one *Server ▸ Configure…* shows. `PLESTY_BENCH_TOKEN` sets a default. |
| `--timeout S` | How long to wait for each reply, in seconds. |

```bash
export PLESTY_BENCH=lab-bench-03 PLESTY_BENCH_TOKEN=…
plesty-bench status
plesty-bench install k10cr1-dev
plesty-bench update k10cr1-dev --ref feat/homing
plesty-bench field-test k10cr1-dev --gates connect_lifecycle,buffer_drain
plesty-bench reports k10cr1-dev --json
plesty-bench -- start pm100d            # `--` first when the command starts with a dash
```

`install`, `update` and `field-test` are started on the bench and their log is
followed here until they end, so a dropped connection costs you the output,
not the work.

## The client's own commands

Three commands run here rather than on the bench:

### `ping`

```bash
plesty-bench ping
```

Whether the agent answers.

### `fetch`

```bash
plesty-bench fetch PATH [-o OUT]
```

Copies a file from the bench home to this machine — how a field-test report
comes back. `reports NAME --json` gives each report's path in the form `fetch`
takes. Only files under the bench home, up to 16 MB, can be fetched.

### `control`

```bash
plesty-bench control DEVICE …
```

Opens [the Control window](../gui/devices.md#control-the-control-window) on this machine with a panel per
named device, each driving it through the agent. It needs the `control` extra
and a display.

## From Python

The same connection as a library, for scripts and notebooks:

```python
from plesty.bench import BenchClient

with BenchClient("lab-bench-03", token="…") as bench:
    print(bench.exec(["status", "--json"]).json())

    job = bench.exec(["field-test", "k10cr1-dev", "--no-wait"]).stdout.strip()
    bench.follow(job, print)  # print the job's log until it ends
    path = bench.exec(["reports", "k10cr1-dev", "--json"]).json()[0]["home_relative"]
    report = bench.fetch(path)  # the file's bytes

    meter = bench.device("pm100d")  # an instrument, through the agent
    meter.query("wavelength")
    meter.write("wavelength", 780.0)
```

| Call | Returns |
|---|---|
| `exec(argv)` | An `ExecResult`: `code`, `stdout`, `stderr`, `.ok`, `.json()`. |
| `follow(job_id, on_line)` | The job's exit code, once it ends. |
| `fetch(path)` | The file's bytes. |
| `device(name)` | A `RemoteDevice` with `describe()`, `query(key)`, `write(key, value)`, `call(op, **kwargs)`. |
| `describe()`, `ping()` | The bench's version and capabilities; whether it answers. |

The full reference is in the [API reference](../api_reference.md).