`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. Each command below is also available from another machine as plesty-bench <command> — see plesty-bench.

For a walkthrough rather than a reference, start from Usages.

Declaring devices

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.

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.

Modules — the bench’s store

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

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

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

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.

Field tests and jobs

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.

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

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.

Maintenance

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.

Agent and console

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.

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 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.

plesty-server