Getting started (with the CLI)

Installing the Python library 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.

pip install bruce-models

bruce --help
bruce --version

There is also a public Docker image, 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.

# 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.

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.

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.

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.

# 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.

# 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

# 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.