# The Command Line

Starting an experiment always involves the same questions: which settings file,
where the runs go, a new run or the continuation of a stopped one, a trial without
instruments. `ExperimentCLI` (from `plesty.lib.experiment`) answers them the same way
for every experiment, so each experiment only supplies what is its own: which devices
it uses, and how it is built.

## A minimal command line

```python
# power_scan.py
import sys

from plesty.lib.device.composite_device import CompositeDevice
from plesty.lib.experiment import ExperimentCLI, Manifest

cli = ExperimentCLI(Manifest(module="power_scan", title="Power scan"))


@cli.rig
def rig(args, config, skip):
    return CompositeDevice(["pm"])


@cli.build
def build(args, config, run_root, devices):
    return PowerScan(config, devices=devices, run_root=run_root)


if __name__ == "__main__":
    sys.exit(cli.main())
```

`PowerScan` is the experiment class from
[Write the scan](../quickstart/experiment.md#write-the-scan). The two functions are
required:

- **`@cli.rig`** builds the devices the experiment uses (PLESTY calls them its
  **rig**). It receives the parsed command-line arguments (`args`), the settings
  (`config`), and `skip`, the names of optional devices the operator chose to go
  without (see [Checking the Devices Before a Run](checking_devices.md)). It is
  called again each time the operator retries after a device failed to answer.
  Return `None` for an experiment that uses no devices.
- **`@cli.build`** builds the experiment. It receives `args`, `config`, the folder to
  save runs in (`run_root`) and the devices; `devices` is `None` in a dry run, where
  nothing is connected.

## Options

| Option | Does |
|---|---|
| `-c FILE`, `--config FILE` | read the settings from `FILE` instead of the default, `config/default.yaml` (see [The run configuration: `config/*.yaml`](../common/yaml_config.md#the-run-configuration-configyaml)) |
| `--run-root FOLDER` | save the run in `FOLDER` instead of the default |
| `-r RUN_ID`, `--resume RUN_ID` | continue a stopped run (see [Stopping and Continuing a Run](stopping.md)) |
| `--run-id NAME` | name the new run `NAME` instead of `<experiment>_<date>-<time>` |
| `--dry-run` | build and print the plan, connect nothing |
| `--manifest` | print what the experiment declares, as JSON (see [What the experiment declares](#what-the-experiment-declares)) |
| `--devices` | print the devices of `setup.yaml` a run of these settings uses, as JSON — `{"devices": ["hwp", "spec"]}`, or `{"devices": null}` for all — and connect nothing |

A settings file that does not exist counts as empty settings, so an experiment whose
defaults are all in its code runs without one.

When a `setup.yaml` exists (see [The Setup File](setup_file.md)), the command line
reads it before anything connects. If a variable it names has no value, the run stops
there and says which variables to set in which file. Only the benches of the devices
the run uses count: see `@cli.needs` below.

## Exit codes

| Code | Means |
|---|---|
| `0` | the run completed, or the plan or manifest was printed |
| `1` | a device did not answer and the operator chose to stop (see [Checking the Devices Before a Run](checking_devices.md)), or the run was aborted |
| `2` | a variable named by `setup.yaml` is not set |
| `130` | the run was interrupted with `Ctrl-C` or canceled; it can be continued with `--resume` |

## Optional functions

Register these the same way, as decorators, when you need them:

| Decorator | Called | Use it to |
|---|---|---|
| `@cli.configure` | with `args` and the loaded settings, before the plan is built | change the settings from command-line options; return the settings to use |
| `@cli.check` | with `args` and the settings, before any device connects | refuse incomplete settings: raise an exception with the reason |
| `@cli.default_config` | with `args`, when no `-c` was given | choose another settings file from other options, such as a `--demo` flag; return `None` for the default |
| `@cli.finished` | with `args`, the settings and the run folder, when the run completed | print a summary of what was measured; return the text |
| `@cli.needs` | with the settings, before anything connects | name the devices of `setup.yaml` these settings use, or return `None` for all of them. PLESTY Bench then starts only those, and the run needs only their benches set up |

```python
@cli.needs
def needs(config):
    # Measuring in place uses one bench; navigating to dots uses the camera bench too.
    return ["hwp", "qwp", "spec", "pm"] if not config.get("dots") else None
```

`cli.optional("pm", …)` names devices the run can do without: if only these fail to
answer, the operator may continue without them.

## Your own options

`cli.add_argument` adds an option, with the same arguments as
`argparse.ArgumentParser.add_argument`. `sets=` names the setting the option
replaces, so that programs reading the manifest know what it does:

```python
cli.add_argument("--points", type=int, sets="points", help="Number of scan points.")


@cli.configure
def configure(args, config):
    if args.points is not None:
        config["points"] = args.points
    return config
```

## What the experiment declares

`Manifest` describes the experiment to programs that start it for you, such as a
console with a form for the settings. `--manifest` prints it without connecting
anything or reading any settings, so such a program can ask an experiment what it
takes before anything is set up.

| Field | Holds |
|---|---|
| `module` | the name the experiment is started by, as in `python -m <module>` |
| `title` | a human-readable name |
| `schema` | the settings the experiment takes, each with its type, unit and description, in the same form as a device's parameters |
| `environment` | the environment variables it reads; `env_vars("PM_ADDRESS", …)` builds them |
| `options` | the extra command-line options; filled in by `cli.add_argument` |
| `config` | the default settings file, `config/default.yaml` |
| `run_root` | the default folder for runs, `runs` |
| `viz` | the module of the experiment's viewer, if it has one (see [3. Watch the data](../quickstart/terminal.md#3-watch-the-data)) |