Runbook: altaforge-ra-cli Setup¶

One-time setup guide for altaforge-ra-cli, the command-line tool used for Research Assistant support operations. Complete this before following any other runbook that uses the CLI.

Prerequisites¶

The govlab-ls-research-assistant repository is cloned locally.
uv is installed and on PATH.
Your Azure account has the appropriate role on the App Registration for the target environment. Contact a developer if you are unsure.

1. Install the CLI¶

From the repository root:

make install-cli

This installs the altaforge-ra-cli binary as a uv tool and makes it available on your PATH. Re-running the command upgrades to the latest version. Verify with:

altaforge-ra-cli --help

2. Configure Profiles¶

Profiles store per-environment connection details so you do not have to type --base-uri, --client-id, and --tenant-id on every command. Profiles are saved in ~/.config/altaforge-ra-cli/config.json.

Obtain the values below from the deployment documentation or a developer before running these commands.

Choosing the API base URI¶

The --api-base-uri value can point to either:

Frontend URL + /api (recommended for Tier 1) — traffic routes through the nginx reverse proxy. Example: https://my-app.example.com/api. This is publicly accessible and requires no special network access.
Backend URL directly — bypasses nginx. Example: https://backend.internal.example.com. This URL is restricted to the virtual network and will not be reachable unless you are connected via VPN or are operating from within the network.

Use the frontend proxy URL unless a developer has specifically told you to use the direct backend URL.

UAT profile¶

altaforge-ra-cli config profile set uat \
  --api-base-uri   https://<uat-frontend-hostname>/api \
  --ms-client-id   <uat-app-registration-client-id> \
  --ms-tenant-id   <azure-tenant-id>

PROD profile¶

altaforge-ra-cli config profile set prod \
  --api-base-uri   https://<prod-frontend-hostname>/api \
  --ms-client-id   <prod-app-registration-client-id> \
  --ms-tenant-id   <azure-tenant-id>

Set a default profile¶

If you work with one environment most of the time, set a default to avoid typing --profile on every command:

altaforge-ra-cli config default set prod

To switch the default:

altaforge-ra-cli config default set uat

Inspect or list profiles¶

altaforge-ra-cli config profile list          # names only
altaforge-ra-cli config profile show prod     # full JSON for one profile

3. Authentication¶

The CLI authenticates via Microsoft Entra ID (MSAL). Tokens are cached automatically; you are only prompted to sign in when no valid cached token exists (typically every 90 days of inactivity).

altaforge-ra-cli --profile prod auth ms get-token

By default this uses device code flow: the CLI prints a short URL and a one-time code to the terminal. Open the URL in any browser, enter the code, and complete sign-in. The CLI waits and receives the token automatically once you are done.

You do not need to run this before each API operation. The CLI acquires a token silently in the background whenever one is needed. Run it manually only to verify authentication or pre-warm the cache.

Inspect the current token¶

altaforge-ra-cli --profile prod auth ms get-token --decode

Clear the token cache¶

altaforge-ra-cli auth ms purge-token-cache