# `plesty-server`

Every command the bench application takes, grouped as the console groups
them. The options every command shares — which home, which fleet file — are
in [the CLI overview](index.md). Each command below is also available from
another machine as `plesty-bench <command>` — see [`plesty-bench`](plesty-bench.md).

For a walkthrough rather than a reference, start from [Usages](../usage/index.md).

## Declaring devices

```bash
plesty-server fleet init [PATH] [--force]     # write an annotated fleet.yaml (default ./fleet.yaml)
plesty-server declare NAME PACKAGE [--version V | --git URL --ref REF]
                                   [--arg X …] [--env K=V …] [--no-autostart]
                                   [--fleet FLEET]
plesty-server list [--no-probe] [--json]      # name, source, installed version, state, port
plesty-server fleet new FLEET                 # an empty fleet: <home>/fleets/FLEET.yaml
plesty-server fleet list [--json]             # every fleet, its file and device count
```

`--arg` and `--env` repeat, once per value: `--arg --address --arg "USB0::…"`.
`declare` allocates a port unless the args or env name one, and writes the
fleet file back — the current fleet, the one that already declares NAME, or
`--fleet FLEET`. A new bench starts on an empty `<home>/fleets/default.yaml`,
so the agent and the console share one file. A name is declared in one fleet
of a bench only: it names the device's folder, log and process record. Every
write re-reads its file first, so neither the console nor the agent writes
over what the other declared. The keys it writes are in
[Files and settings](files.md#the-fleet-file).

`fleet new` leaves the current fleet current; through `plesty-bench -b BENCH
fleet new cryo` and `plesty-bench -b BENCH declare … --fleet cryo` a client
sets up a fleet on another bench.

In the console: *Device ▸ Add device…* — see [Declare device](../gui/devices.md#declare-device).

## Modules — the bench's store

```bash
plesty-server module list [--json]
plesty-server module install PACKAGE [--version V] [--git URL --ref REF]
                                     [--force] [--no-wait]
plesty-server module load FOLDER [--ref BRANCH] [--no-wait]
```

Stocks the bench; names no device and needs no fleet. `module install` of a
version not yet on PyPI falls back to the module's repository at tag
`v<version>`. `module load` records a module's repository already on this
machine where it lives — nothing is copied — and runs it with the folder's own
`.venv`; `--ref` checks that branch out in the folder first.

In the console: *Hub ▸ Browse…* and *Hub ▸ Load from…*; *Hub ▸ Installed
modules…* lists and uninstalls what either put on the bench.

## Installing what a device declares

```bash
plesty-server install NAME [--force] [--no-wait]
plesty-server update NAME [--ref REF] [--no-wait]
plesty-server uninstall NAME
```

These run as jobs: the command streams the job's log and exits with its code,
unless `--no-wait` prints the job id instead.

- `update` on a **checkout** pulls it and re-syncs; with `--ref`, it installs a
  checkout at that ref *beside* the old one and points the declaration at it.
  On a **release** it reinstalls the same version — pointing a device at a
  newer release is an edit to its declaration followed by `install`.
- `uninstall` stops the server, then removes its environment unless another
  declared device still uses it.

## Servers

```bash
plesty-server start NAME [--no-wait] [--timeout S]
plesty-server stop NAME [--timeout S]
plesty-server restart NAME [--no-wait]
plesty-server status [NAMES…] [--no-probe] [--json]
plesty-server log NAME [-n 50]
plesty-server clear-log NAME
```

- `start` needs a declaration. It installs first when nothing on the bench
  serves it, then waits — 30 s unless `--timeout` says otherwise — until the
  server answers `describe`, not merely until the process exists.
- `stop` asks before it insists: a clean stop request first, so the module
  closes the instrument, then a terminate, then a kill. `--timeout` is how long
  the clean step is given.
- `status` prints `NAME STATE PID PORT STARTED DETAIL` per server; `--json`
  adds the exit code of one that ended. The states are `stopped`, `starting`,
  `running` (answering on its port) and `exited` (it died — `log` says why).
  `--no-probe` reports the process only, without asking the server.
- `clear-log` empties the log, and with it the console's Traffic history.

## Fleet

```bash
plesty-server fleet up [NAMES…] [--no-install] [--no-wait]
plesty-server fleet down [NAMES…]
plesty-server fleet status [--no-probe]
plesty-server fleet run [NAMES…] [--interval 5] [--agent] [--bind ENDPOINT]
                        [--token …] [--leave-running]
```

| Command | With no NAMES |
|---|---|
| `fleet up` | Installs what is missing and starts the **working fleet** — the devices marked `autostart`, the checked rows in the console. Exits 1 when any device ended `exited` or `stopped`, so a startup script can report it. |
| `fleet down` | Stops the working fleet **and** every other server started here. |
| `fleet status` | Takes no names: shows every declared device. |
| `fleet run` | Brings the working fleet up and keeps it up: every `--interval` seconds a device found `exited` is started again, after a backoff that doubles per consecutive crash (1, 2, 4 … 60 s). A device you stopped on purpose is left alone. Ctrl-C or a service manager's stop brings the servers down with it, unless `--leave-running`. `--agent` also serves `plesty-bench` clients from the same process. |

`fleet run --agent` is what a bench with nobody logged in should run — see
[Keep a bench up without a window](../usage/headless.md).

## Field tests and jobs

```bash
plesty-server field-test NAME [--tier host|client] [--address A] [--gates a,b]
                              [--repetitions N] [--keep-going] [--keep-server]
                              [--no-wait] [-- EXTRA…]
plesty-server reports NAME [--json]
plesty-server jobs list [--name NAME] [--kind KIND] [--json]
plesty-server jobs log JOB_ID [--follow] [--offset N] [--json]
plesty-server jobs cancel JOB_ID
```

The gates are `discovery`, `connect_lifecycle`, `param_roundtrip`,
`param_constraints`, `functions`, `buffer_drain`, `stability` and
`error_recovery`; a module's script may accept fewer. The options are
explained in [Field-test a device](../usage/field_test.md#the-options).

`jobs cancel` kills the job's process tree. For an experiment's run that
means the devices it started are **not** stopped — stop the run from the
console instead, or stop them by hand.

## Serving an experiment's run

```bash
plesty-server serve NAME --entry JSON [--json]
plesty-server share-check ROOT PROBE --reply FILE [--json]
```

What **Run** asks of each bench in an experiment's setup, through its agent;
you rarely type them. `serve` makes sure device NAME is running here, declared
from its `setup.yaml` entry (given as JSON) — declared fresh when the bench
lacks it, re-declared and restarted when the entry differs — and reports the
port. `share-check` reads PROBE under ROOT and writes FILE beside it, which is
how the bench that starts a run checks that every bench sees the same shared
data folder. See [Run an experiment](../usage/experiment.md#what-run-does).

## Maintenance

```bash
plesty-server purge --list [--json | --tsv FILE]
plesty-server purge PARTS… --yes
plesty-server purge --all --yes
```

The parts are `logs`, `state`, `packages`, `tools` and `config`, and each
item `--list` names under them — `module:<package>`, `fleet:<file>`,
`device:<name>`, … — can be named on its own; `--all` removes the home
directory itself. `--tsv` writes the items, grouped, for the Windows
uninstaller's list. What each one holds is in
[Remove only part of the data](../usage/uninstall.md#remove-only-part-of-the-data).

## Agent and console

```bash
plesty-server agent [--bind tcp://*:5550] [--token …] [--workers 4]
plesty-server gui [--title TEXT]
```

`agent` takes its defaults from `<home>/agent.yaml`; every option overrides
it.

```bash
plesty-server data-path [SHARE [--folder FOLDER] | --clear]
```

`data-path` shows the bench's **Plesty share** — the lab's shared disk as this
machine mounts it — and its **folder** in it, under which every device it
starts writes; or sets them. `SHARE` must be mounted; `FOLDER` is a path inside
it, created when missing, and the share itself when left out. They are the
**Plesty share** and **Bench folder** of *Server ▸ Configure…*;
`plesty-bench -b BENCH data-path SHARE --folder FOLDER` sets another bench's. `gui` opens [the console](../gui/index.md) and needs the `gui` extra, which
the installers include.

## Machine-readable output

`list`, `status`, `module list`, `reports`, `jobs list`, `serve`,
`share-check` and `purge --list` take `--json`. `jobs log JOB_ID --offset N
--json` returns `{text, offset, running, returncode, state}`, which is what a
tailing client polls.

## Hidden commands

`plesty-server _job install|module-install|module-load|update|field-test …`
are the foreground twins that jobs execute; `_job experiment-run` runs an
experiment module, stops the devices its run started and writes the run's
report; and `_launch` is the detached launcher. The bench runs them; people do
not. See [Process management](../design/processes.md).