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

# Chiplab CLI

> Run Chiplab test suites from a terminal or a CI pipeline, without an agent.

`chiplab-cli` is Chiplab's command-line client. It runs a [test suite](https://docs.veecle.ai/tools/test.md) against a firmware ELF on a virtual board, the same way your agent does over MCP, and reports whether the tests passed. Each outcome has its own exit code, so it fits as a step in a [CI pipeline](https://docs.veecle.ai/use-cases/ci-on-every-pr.md).

Source and releases are at [github.com/veecle/chiplab-cli](https://github.com/veecle/chiplab-cli).

## Install

In GitHub Actions, use [`veecle/install-chiplab`](https://github.com/veecle/install-chiplab). It downloads the release for the runner, verifies it, and adds `chiplab-cli` to `PATH`:

```yaml theme={null}
- uses: veecle/install-chiplab@v1
```

Elsewhere, each [release](https://github.com/veecle/chiplab-cli/releases) has prebuilt binaries for Linux (x86\_64 and aarch64, statically linked) and macOS (Apple Silicon):

* `chiplab-cli-x86_64-unknown-linux-musl.tar.gz`
* `chiplab-cli-aarch64-unknown-linux-musl.tar.gz`
* `chiplab-cli-aarch64-apple-darwin.tar.gz`

```sh theme={null}
curl -fsSLO https://github.com/veecle/chiplab-cli/releases/latest/download/chiplab-cli-x86_64-unknown-linux-musl.tar.gz
curl -fsSLO https://github.com/veecle/chiplab-cli/releases/latest/download/sha256sums.txt
sha256sum --check --ignore-missing sha256sums.txt
tar -xzf chiplab-cli-x86_64-unknown-linux-musl.tar.gz
./chiplab-cli --help
```

On macOS, use `shasum -a 256 --check --ignore-missing sha256sums.txt`. To pin a version, replace `latest/download` with `download/<tag>`, for example `download/v0.1.0`.

> [!NOTE]
>
> The macOS binary is not signed. When it is downloaded through a browser, macOS blocks it. Remove the quarantine attribute with `xattr -d com.apple.quarantine chiplab-cli`.

It also builds from source with `cargo`, or runs with Nix:

```sh theme={null}
cargo install --locked --git https://github.com/veecle/chiplab-cli --tag v0.1.0 chiplab-cli
nix run github:veecle/chiplab-cli/v0.1.0 -- --help
```

## Authenticate

The CLI reads a personal access token (`veecle_pat_...`) from the `CHIPLAB_TOKEN` environment variable. Create one on [API keys](https://docs.veecle.ai/platform/api-keys.md).

The token acts as the user who created it, with access to all their projects. Keep it out of the repository, and revoke it once it is no longer needed.

## Run a test suite

```sh theme={null}
chiplab-cli run-test-suite \
  --project <project_id> \
  --firmware path/to/firmware.elf \
  --test-suite tests/chiplab.test.ts \
  --board chiplab-board.json \
  --download-dir chiplab-artifacts
```

It takes the same inputs as [`run_test_suite`](https://docs.veecle.ai/tools/test): a `project_id`, the firmware ELF, the suite file, and a JSON file with the `board` object, such as `{ "model": "stm32f4_discovery", "uarts": ["usart2"] }`. `--download-dir` saves the run's artifacts.

`chiplab-cli --help` lists the commands. `chiplab-cli <command> --help` describes each command's arguments, its machine-readable output, and its exit codes.

## Limits

The [test suite limits](https://docs.veecle.ai/tools/test.md#limits) apply as they do over MCP. Every run uses credits (see [Usage](https://docs.veecle.ai/platform/usage.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.