Configuration

Configuration

reportmateutil needs two things: the API endpoint and a credential. It has no config file of its own, no profiles and no login command. Instead it resolves each value from the first source that has it, so on an admin machine that runs the ReportMate app, or a managed machine that runs the device runner, there is usually nothing to set. Explicit environment variables always win.

reportmateutil config prints what was resolved and where each value came from, with no secret material.

reportmateutil config

Resolution order

The endpoint comes from the first of:

1. REPORTMATE_API_URL.
2. The ReportMate app's saved connection (connection.json, below).
3. The device runner's preferences (below).

Trailing slashes are stripped.

The credential comes from the first of:

1. The environment: REPORTMATE_API_KEY, then REPORTMATE_TOKEN, then REPORTMATE_PASSPHRASE.
2. The ReportMate app's saved connection, by the method the app records in authMethod:
   • entraBearer — a token from az account get-access-token for the Entra audience (from REPORTMATE_OIDC_AUDIENCE or the app's oidcAudience).
   • apiKey — the API key the app stored in the macOS Keychain.
   • passphrase — the passphrase the app stored in the macOS Keychain.
   • no method recorded — the Keychain API key, else the Keychain passphrase.
3. Entra sign-in for the deployment, ahead of any shared secret on the machine. The audience comes from REPORTMATE_OIDC_AUDIENCE, the app's connection, or the API's own GET /api/v1/auth/config when OIDC is enabled there (5-second timeout). The audience is exchanged for a token with az account get-access-token. Nothing is stored.
4. The device runner's preferences: on Windows the read-scoped ReadApiKey, then the shared passphrase; on macOS the shared passphrase. The runner's ingest-only ApiKey is never used for reads.
5. An AWS-hosted deployment: the client passphrase from AWS Secrets Manager, read with your aws session. The CLI treats the deployment as AWS when the app's connection says cloud: aws, when REPORTMATE_CLOUD=aws, or when the API host ends in .amazonaws.com or .awsapprunner.com or contains .execute-api.. The secret id is REPORTMATE_AWS_SECRET_ID, default reportmate/client-passphrase.

When a step is tried and fails (for example az returns no token), the reason is kept as a note: config prints it, and the no credential error lists it.

REPORTMATE_NO_DISCOVERY=1 (also true or yes) confines resolution to the environment: the app's connection.json, the runner's preferences, Entra discovery and AWS Secrets Manager are all skipped. Use it in CI and in scripts that must not pick up the machine's own connection. On macOS, when the environment holds no credential, the app's Keychain item is still looked up even with discovery off, so set a credential in the environment as well.

Environment variables

Variable	What it does
REPORTMATE_API_URL	Base URL of the API
REPORTMATE_API_KEY	Scoped per-client key, rm_<id>_<secret>. Sent as X-API-Key. Preferred
REPORTMATE_TOKEN	An OIDC bearer token (JWT). Sent as Authorization: Bearer
REPORTMATE_PASSPHRASE	Shared client passphrase. Sent as X-Client-Passphrase
REPORTMATE_OIDC_AUDIENCE	Entra audience to request a token for through az
REPORTMATE_INTERNAL_SECRET	Internal-service secret, sent as X-Internal-Secret on every request. Needed only by settings set and settings discover
REPORTMATE_CLOUD	aws marks the deployment as AWS-hosted for step 5
REPORTMATE_AWS_SECRET_ID	Secrets Manager id of the client passphrase. Default reportmate/client-passphrase
REPORTMATE_NO_DISCOVERY	1, true or yes to read the environment only

Values are trimmed; an empty or whitespace-only variable counts as unset.

RM_VERSION is read at compile time only; see Development.

export REPORTMATE_API_URL=https://reportmate.example.com

export REPORTMATE_API_KEY=rm_example_notarealsecret

On Windows PowerShell:

$env:REPORTMATE_API_URL = "https://reportmate.example.com"

$env:REPORTMATE_API_KEY = "rm_example_notarealsecret"

The app's saved connection

ReportMate for Mac writes its non-secret connection to connection.json. The CLI looks for the file at:

Platform	Path
macOS	~/Library/Application Support/ReportMate/connection.json
Windows	%ProgramData%\ReportMate\connection.json
Linux	$XDG_CONFIG_HOME/reportmate/connection.json, else ~/.config/reportmate/connection.json

Keys read: apiUrl (or apiBaseUrl), authMethod (entraBearer, apiKey, passphrase), oidcAudience and cloud.

ReportMate for Windows keeps its connection in the registry it shares with the Windows runner (HKLM\SOFTWARE\ReportMate\Settings), so on Windows the app's endpoint and ReadApiKey arrive through the runner step below rather than through connection.json.

A secret the app uses comes from the macOS Keychain generic-password item with service com.github.reportmate.mac and account ApiKey or Passphrase. macOS asks once to allow the CLI to read it. The Keychain is touched only for a secret, never for the endpoint, method or audience. On Windows and Linux the app's saved secrets are not read.

The device runner's preferences

Platform	Source	Values
macOS	defaults read com.github.reportmate	ApiUrl, Passphrase
Windows	HKLM\SOFTWARE\Policies\ReportMate, then HKLM\SOFTWARE\ReportMate\Settings, then HKLM\SOFTWARE\ReportMate	ApiUrl, ReadApiKey, Passphrase

On Windows the first key that holds a value wins, so a policy (Intune CSP or Group Policy) overrides what the app writes under Settings, which overrides the base key.

Multiple instances

With no profiles, point at a second API for one command by setting the variables inline.

REPORTMATE_NO_DISCOVERY=1 REPORTMATE_API_URL=https://staging.example.com reportmateutil devices --limit 5

Fixed behaviour

Behaviour	Value
HTTP timeout	600 seconds, hard-coded
TLS	rustls with a bundled root store; the OS trust store is not consulted and there is no --insecure
User agent	reportmateutil/<version>
Accept header	application/json, text/plain;q=0.9, */*;q=0.8
Proxy	HTTPS_PROXY / HTTP_PROXY / NO_PROXY, honoured by the HTTP library
Retries	none