# Command line

`plesty-server` is the headless face of the bench. Every command opens the
bench for `--home DIR` (default `~/.plesty/server`, or `PLESTY_SERVER_HOME`)
and `-f FILE` (default: `./fleet.yaml`, then `<home>/fleet.yaml`) and calls
one `Bench` method; `-q` silences progress lines (they go to stderr, results
to stdout).

## Declaring devices

```bash
plesty-server fleet init                      # write an annotated fleet.yaml here
plesty-server declare pm100d plesty-pm100d --version 0.2.1 \
    --arg --address --arg "USB0::0x1313::…::INSTR" --env PLESTY_REPORT_ARCHIVE=/shares/reports
plesty-server declare pm100d-dev plesty-pm100d --git https://gitlab.com/…/plesty-pm100d.git --ref exp \
    --no-autostart
plesty-server list                            # name, source, installed version, state, port
```

`declare` allocates a port (5551 upwards, 5550 is the agent's) unless the
args or env name one, and writes the fleet file back — creating
`<home>/fleet.yaml` when the bench has no fleet file yet, because a
declaration only reaches the jobs (separate processes) through a file.

A port the bench allocated is re-allocated on `start` when something else has
taken it meanwhile — another bench on the same machine, or a server left over
from an earlier start — and the new one is written back too. A port named in
`args`/`env` is reported as busy instead: that number is passed to the device,
so starting elsewhere would contradict its own arguments.

## Modules — the bench's store

```bash
plesty-server module list                     # what is installed here, and from where
plesty-server module install plesty-pm100d    # a release; --version pins it
plesty-server module install plesty-pm100d --git https://gitlab.com/…/plesty-pm100d.git --ref exp
```

A module install stocks the bench; it names no device and needs no fleet. A
release that is not on PyPI (yet) falls back to the repository at the
matching tag, so `module install plesty-k10cr1 --version 0.1.1` lands `v0.1.1`
either way.
`declare` then makes instances of what is in stock. A release install needs
only `uv`; a `--git` install needs `git`, which the bench finds on `PATH`,
where Windows puts it, or — on Windows, having neither — installs for itself
under `<home>/tools/git` (`PLESTY_SERVER_AUTO_GIT=0` refuses and reports).

## Installing

```bash
plesty-server install pm100d                  # runs as a job; streams its log; exit code = job's
plesty-server install pm100d --no-wait        # prints the job id instead
plesty-server update pm100d-dev --ref main    # pull + uv sync (git) / reinstall (PyPI)
plesty-server uninstall pm100d                # stops it, removes the env unless another device uses it
```

## Servers

```bash
plesty-server start pm100d                    # installs first when nothing serves the spec; waits for `describe`
plesty-server status                          # every declared device; --no-probe for pid only
plesty-server status pm100d k10cr1
plesty-server log pm100d -n 100
plesty-server restart pm100d
plesty-server stop pm100d --timeout 5        # interrupt → terminate → kill
```

## Fleet

```bash
plesty-server fleet up                        # install + start every autostart device
plesty-server fleet up pm100d k10cr1          # or these
plesty-server fleet status
plesty-server fleet down
```

`fleet up`, `fleet down` and `fleet run` act on the **working fleet** — the
devices marked `autostart` (the check column in the console) — unless NAMES
are given. `fleet up` exits 1 when any device ended `exited` or `stopped`.

```bash
plesty-server fleet run [NAMES] [--interval 5] [--agent] [--leave-running]   # keep the fleet up (headless)
```

## Field tests and jobs

```bash
plesty-server field-test pm100d-dev --gates connect,drain -- --repetitions 5
plesty-server reports pm100d-dev
plesty-server jobs list [--name pm100d-dev] [--kind install]
plesty-server jobs log <job-id> [--follow]
plesty-server jobs cancel <job-id>
```

See [Field tests](field_test.md) for what happens around the server.

## Machine-readable output

`list`, `status`, `reports`, `jobs list` take `--json`; `jobs log <id> --offset N --json`
returns `{text, offset, running, returncode, state}` for tailing clients.

## Agent

```bash
plesty-server agent [--bind tcp://*:5550] [--token …]   # serve plesty-bench clients
```

See [Remote benches](remote.md).

## The console

```bash
plesty-server gui                             # the Qt window on this bench (needs the gui extra)
```

## The hidden `_job` group

`plesty-server _job install|update|field-test …` are the foreground twins
the jobs execute; the launcher runs them, people do not.