> ## Documentation Index
> Fetch the complete documentation index at: https://instro.nominal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Command-line tools for working with instro

`instro` ships a command-line interface for inspecting and discovering instruments on your bench.

## Running the CLI

The CLI comes with the `instro` package — see [Installation](/instrumentation/installation) for adding it to your project. In a project that has `instro` installed, run commands with `uv run`:

```bash theme={null}
uv run instro discover
```

To try a command once without installing anything, `uvx` runs it in a throwaway environment:

```bash theme={null}
uvx instro discover
```

`uvx` can be slow when it triggers a fresh install of `instro`'s full dependency tree. For regular use, put `instro` on your PATH instead so you can call it from anywhere:

```bash theme={null}
uv tool install instro
instro discover
```

## instro --version

Prints the installed version of the core `instro` package followed by every optional workspace package (`instro-contrib`, `instro-unstable`, `instro-ethernetip`, `instro-daq-ni`, `instro-daq-labjack`, `instro-daq-mcc`, `instro-i2c-aardvark`). Packages that are not installed are marked `not installed` with the `pip install "instro[<extra>]"` command that provides them — see [Additional Packages](/instrumentation/installation#additional-packages) for what each extra covers.

```bash theme={null}
instro --version
```

The full roster is printed on purpose: attach the output to bug reports as an environment summary.

## instro discover

Scans all available VISA resources and serial ports, queries each instrument for its identity, and prints a summary table.

To force a specific VISA backend, pass `--backend`:

```bash theme={null}
uv run instro discover --backend=@py
uv run instro discover --backend "@ivi"
```

<Note>
  The `@ivi` backend finds an available IVI-compliant backend on your system e.g. NI-VISA or Keysight IO. `@ivi` is more reliable for USB and GPIB instruments. The `@py` backend (`pyvisa-py`) is a pure-Python fallback that works without NI-VISA installed but may not detect all instruments.
</Note>

### Output

Before scanning, the command prints which VISA backend is active (`@ivi`, or `@py` when no IVI VISA is installed). On the `@py` backend it also lists any interfaces the scan cannot cover — for example `GPIB: unavailable — gpib_ctypes is installed but could not locate the gpib library (install NI-488.2 or linux-gpib)` — so you know when an empty result reflects a missing library rather than an empty bench. These notes are informational; the scan still runs and the command exits 0.

The command groups results into up to three tables.

**Recognized devices** — instruments with a known driver. The table shows the VISA resource address, instrument category, and the `instro` driver class to use.

**Serial devices** — serial ports detected by the OS. These are listed separately because serial instruments require manual configuration; `instro discover` cannot query them automatically.

**Unrecognized devices** — instruments that responded to `*IDN?` but did not match any known driver. The raw IDN response is shown so you can identify the device.

If no devices are found at all, the command prints a single error panel; on the `@py` backend the panel repeats any unavailable interfaces.

### Using a recognized device

Pass the resource address from the **Recognized devices** table directly to the driver's constructor:

```python theme={null}
from instro.psu.drivers.bk_9115 import BK9115
from instro.psu import InstroPSU

psu = InstroPSU(name="psu", driver=BK9115("USB0::0x15EF::0x0099::INSTR"), num_channels=1)
psu.open()
```

### Unrecognized devices

If your instrument appears in the **Unrecognized devices** table, `instro` does not yet have a driver for it. See [Custom instruments](/instrumentation/custom-instruments) for how to author one, or [instro-contrib](/instrumentation/contrib) to check for community-contributed drivers.