Skip to content

cli

Jump to bottom
Peter Holloway edited this page Aug 28, 2025 · 3 revisions

CLI

To make debugging easier when working in a terminal, numtracker provides a client subcommand for querying a running service.

This client is available via numtracker client and help for the available commands is available from numtracker client --help. Help is also available for individual subcommands.

Note

By default the client expects the service to be running at http://localhost:8000 (the default when running a server locally for development) but the server host can be specified via the --host (or -H) option.

numtracker client --host https://numtracker.example.com configuration

If authentication is required, the auth provider can be set via the --auth option.

numtracker client --auth https://authn.example.com/realms/master

Accessing the CLI

The CLI client is the same binary/executable as the numtracker service. To access the command, you can either build locally or use the published container.

Building locally

Note

This relies on having the rust toolchain available. If it is not, the container approach is recommended.

Clone the numtracker repository and from the root of the project run cargo build --release. This will build an executable at ./target/release/numtracker which can then be used directly or moved to a directory on your $PATH.

Using a container

Using a container means you don't need the rust toolchain available, only that you have some container runner (podman or docker). This can make it easier but requires extra steps if persistence is required.

See Running Locally for details.

Available Commands

configuration

Query the service for the current configuration. If no beamlines are specified, this will include all configuration. If a specific beamline is required, the list can be filtered using -b <BEAMLINE_NAME>. This can be repeated to request a selection of beamlines.

# all configuration from the server
numtracker client configuration

# only configuration for i22
numtracker client configuration -b i22

# configurations for listed beamlines
numtracker client configuration -b i22 -b b21 -b i11

If a listed beamline is not present in the service's configuration, it is omitted but is not counted as an error. This means there may be no output if no matching beamlines are available.

visit-directory

Retrieve the visit directory given a beamline and a visit. This uses the configured template to derive the directory to be used and simply prints the path. The visit (and therefore path) do not have to exist.

# Get visit directory for visit cm12345-6 on i22
numtracker client visit-directory i22 cm12345-6

configure

Change the configuration for a beamline. If the beamline already exists, its configuration is updated. Fields for a beamline can be configured individually if the beamline is already present but all fields are required if adding a new beamline.

# Adding a new beamline
numtracker client configure i22\
    --directory '/path/to/{visit}'\
    --scan '{subdirectory}/{instrument}-{scan_number}'\
    --detector '{subdirectory}/{instrument}-{detector}-{scan_number}'

# Updating a single field on an existing beamline
numtracker client configure i22\
    --detector '{subdirectory}/{scan_number}/{detector}-{scan_number}'

The final configuration of the beamline after being updated should be displayed.

Authentication

If the service is configured to required authentication, the client needs to request a token before making any requests. This can be set up by passing the authentication server to the client via the --auth option.

# Query configuration from a service requiring configuration
numtracker client --auth https://authn.example.com/realms/master configuration

The first time this is used, you will be directed to an authentication URL. Once you have granted access to numtracker, tokens will be managed and refreshed when required. If it's needed, the token is stored in ~/.cache/numtracker/refresh.token.

Configuration

Passing --host and --auth is inconvenient when all requests are made to the same server. These values can also be set via the environment variables NUMTRACKER_SERVICE_HOST and NUMTRACKER_AUTH_HOST respectively. They can also be configured in a file in ~/.config/numtracker/config where they should be provided in key = value format (with keys host and auth).

host = "https://numtracker.example.com"
auth = "https://authn.example.com/realms/master"

With these values set the command line flags can still be used to override values on a per-call basis if needed.

Clone this wiki locally