Installation

BenchCI is distributed via PyPI and can be installed using pip.

BenchCI access is tied to a BenchCI account and workspace.

Install BenchCI

Install directly from PyPI:

pip install benchci

Verify the CLI is available:

benchci --help

Upgrade BenchCI

pip install --upgrade benchci

Create or access your workspace

Use the BenchCI dashboard:

https://app.benchci.dev

For early access customers, the BenchCI team activates paid workspace access manually after onboarding or invoicing.

Log in

Log in with your BenchCI email/password account:

benchci login

Check the stored session:

benchci whoami

Remove the session:

benchci logout

Verify your environment

Run diagnostics:

benchci doctor

You can also check a specific bench file:

benchci doctor --bench bench.yaml

Check agent reachability:

benchci doctor --agent http://192.168.1.50:8080

If the agent requires authentication:

benchci doctor --agent http://192.168.1.50:8080 --token "$BENCHCI_AGENT_TOKEN"

Install on a hardware-connected machine

Install BenchCI on the machine that has direct access to hardware:

pip install benchci

Start the Agent:

benchci agent serve

To require authentication:

export BENCHCI_AGENT_TOKEN=secure-token
benchci agent serve

Install on CI or runner machines

A CI runner only needs the BenchCI CLI and network access to the Agent or the BenchCI backend. It does not need direct hardware access for remote runs.

pip install benchci

Example remote Agent run:

benchci run \
  --agent "$BENCHCI_AGENT_URL" \
  --bench bench.yaml \
  --suite suite.yaml \
  --artifact build/fw.elf \
  --token "$BENCHCI_AGENT_TOKEN"

Example registered-bench remote run:

benchci run \
  --agent "$BENCHCI_AGENT_URL" \
  --bench-id my-bench \
  --suite suite.yaml \
  --artifact build/fw.elf \
  --token "$BENCHCI_AGENT_TOKEN"

Example Cloud Mode run:

benchci login

benchci run --cloud \
  --bench-id my-cloud-bench \
  --suite suite.yaml \
  --artifact build/fw.elf

External tools

BenchCI uses Python packages and, depending on your bench, external system tools.

Common Python dependencies include:

  • pydantic

  • pyyaml

  • typer

  • httpx

  • fastapi

  • uvicorn

Transport and GPIO dependencies include:

  • pyserial

  • pymodbus

  • python-can

  • gpiod on Linux

Flashing tools may include:

  • openocd

  • STM32_Programmer_CLI

  • JLinkExe or JLink.exe

  • esptool.py

Use benchci doctor to verify what your current bench needs.