---
title: "Getting started (with the CLI)"
section: "CLI"
route: /cligettingstarted
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Getting started (with the CLI)

Installing the [Python library](/pythongettingstarted) also installs a `bruce` command. It is the same library underneath, so anything the CLI does can be scripted against the models, and anything you configure once is picked up by both.

It exists for the work that does not deserve a script: checking who a credential is and where it points, looking an Account up, listing managed indexes, following an audit, and running seeded end-to-end tests against an installation.

```bash
pip install bruce-models

bruce --help
bruce --version
```

There is also a [public Docker image](/clidocker), if you would rather not install Python at all.

## Logging in and out

`login` stores a default Account and credential so the other commands need no arguments. It accepts either an access token or a username and password.

```bash
# Asks for whatever it still needs.
bruce login

# Or give it up front.
bruce login -e UAT -a your-account -t YOUR_ACCESS_TOKEN

# Forget the stored credential.
bruce logout
```

Every command takes the same overrides, so a stored default can always be stepped around for one call: `-e/--env` (DEV, STG, UAT or PROD), `-a/--account`, `-t/--token`, and `--base-url` / `--guardian-url` for a private installation that is not where the environment implies.

## Using a .env file

Settings can come from a key=value file instead of the stored config, which is the usual choice for CI or for a machine that should hold no credential of its own. A `.env` in the working directory is read automatically.

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

# For a private installation, where the environment does not imply the host.
# NXT_BASE_URL=https://your-account.api.example.com/
# NXT_GUARDIAN_URL=https://login.example.com/
```

To keep reading from a file somewhere else, name it once at login. Only the path is stored, never the credential inside it.

```bash
bruce login --env-file ./deploy/uat.env
```

The layers stack, each one beating the one before it: the stored config file, then a `.env` in the current directory, then a named env file, then the `NXT_*` environment variables, then anything passed on the command line.

## Checking where you are pointed

`status` resolves the stored settings and reports who they belong to, which Account they reach, and **the Hosting Locations that credential manages**. It also names where each setting came from, so a surprising value can be traced to the layer that set it.

```bash
bruce status

# The same thing for a script.
bruce status --json
```

A credential that manages no Hosting Locations reports so rather than failing. Hosting management is what lets `bruce test` build a temporary Account to test in, so this is the command to run first if that is your intent.

## Running tests

`test` runs seeded end-to-end checks: it creates data, exercises a journey through the API, checks the result and then cleans up after itself. Run it with no target to see what can be tested with your credential.

```bash
# What can be tested, and what each test needs.
bruce test

# Choose interactively, against an Account.
bruce test -a your-account

# Or name the selection: a number, a list, a range, a tag, or all.
bruce test 0 -a your-account
bruce test 0,2 -a your-account
bruce test 0-2 -a your-account
bruce test core -a your-account
bruce test all -a your-account
```

The tags are `core`, `import`, `assembly`, `tileset`, `gis`, `historic` and `scale`, and they combine with numbers in the same argument.

Testing a Hosting Location instead of an Account builds a temporary Account, runs there, and removes it afterwards. That is the way to check an installation itself rather than the data already in one account.

```bash
# Pick from the Hosting Locations you manage.
bruce test all -hl

# Or name one by Key or numeric ID.
bruce test core -hl your-location-key
```

`--rows` changes how much data is generated, and `--keep` leaves the generated Entity Type and file behind when you want to look at what a test built. `--cleanup` is the other direction, removing what a test would otherwise keep.

## Other commands

```bash
# An Account's outline, or creating and deleting one.
bruce account show your-account
bruce account create
bruce account delete

# The managed attribute indexes on an Account.
bruce index list -a your-account
bruce index register -a your-account
bruce index delete -a your-account

# Follow the audit as it happens.
bruce audit -a your-account -f
```

Creating and deleting an Account always ask which one and always confirm, whatever default is configured.

---

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/cligettingstarted