---
title: "Running the CLI in Docker"
section: "CLI"
route: /clidocker
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Running the CLI in Docker

The CLI is published as a public image, so an installation can be checked from any machine with Docker and no Python of its own. It is the same `bruce` command described in [Getting started](/cligettingstarted), as the image's entrypoint.

```bash
docker pull nextspace/bruce-cli:latest

docker run --rm nextspace/bruce-cli --help
```

`latest` follows the newest release. Every release is also tagged with the library version it contains, which is what to pin in CI so a run is repeatable.

```bash
docker run --rm nextspace/bruce-cli:0.1.59 --version
```

## Giving it credentials

The image holds no configuration, so settings come in per run. An env file is the usual way, and it keeps the token off the command line and out of the shell history.

```bash
NXT_ENV=UAT
NXT_ACCOUNT=your-account
NXT_TOKEN=YOUR_ACCESS_TOKEN
```

Pass it with `--env-file`. Note this is Docker's own flag reading the file into the container's environment, which is not the same as the CLI's `--env-file` option, though the file format is the same.

```bash
docker run --rm --env-file ./uat.env nextspace/bruce-cli status
```

Individual variables work too, for a CI runner that already holds them as secrets.

```bash
docker run --rm \
    -e NXT_ENV=UAT \
    -e NXT_ACCOUNT=your-account \
    -e NXT_TOKEN="$NXT_TOKEN" \
    nextspace/bruce-cli status --json
```

## Running the core tests

This is the check worth wiring into a pipeline: run the core suite against a Hosting Location, which builds a temporary Account, exercises the journeys and removes it afterwards. It proves the installation works rather than proving one account's data does.

```bash
docker run --rm --env-file ./uat.env \
    nextspace/bruce-cli test core -hl your-location-key
```

Against a specific Account instead, which tests in the data that is already there:

```bash
docker run --rm --env-file ./uat.env \
    nextspace/bruce-cli test core -a your-account
```

`core` is the tag covering the CSV, BRZ, GeoJSON and historic/Scenario journeys. Swap it for `all` to include the assembly alignment and scale tests, or for a number, list or range to run one thing. `bruce test` on its own lists what a credential can run.

The command exits non-zero when a test fails, so a pipeline step needs nothing else to gate on it.

## Things worth knowing

**The container runs as a non-root user** (UID 10001) with its home at `/home/bruce`. Nothing is written outside it, and `--rm` means a run leaves nothing behind at all.

**Nothing is stored between runs.** There is no `bruce login` to do first, because the container is gone afterwards. Mount a config directory at `/home/bruce/.config` if you want a login to persist across runs.

**A private installation needs its urls.** The environment name only implies a host for Nextspace-hosted environments. Set `NXT_GUARDIAN_URL`, and `NXT_BASE_URL` if the Account lookup should be skipped, otherwise the lookup goes to the public Guardian and resolves nothing.

**Test data is real data.** The tests create Entity Types, files and Entities in whatever they are pointed at, and clean up after themselves. Point them at a Hosting Location or a test Account rather than at production.

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/clidocker