Configuration

Place an optional acmad.yaml file at the package root to keep settings that would otherwise be repeated on every command:

site: QCH
site_url: https://acmad.example/

All keys are optional. Values are resolved in this order: command-line option, acmad.yaml, then built-in default. Unknown keys and non-string values are reported as configuration errors.

Configuration key	Command-line option	Built-in default
site	--site	No default; use the workbook value.
site_url	--site-url	http://localhost:8000

Instance configuration

site_url is the only endpoint an operator supplies. Before authenticating, every upload command fetches the instance’s self-describing configuration document and takes the API base, the OIDC issuer, the client identifier and the requested scopes from it:

GET <site-url>/acmad-configuration.json

{
  "schema_version": 1,
  "instance_id": "acmad-prod",
  "display_name": "ANZ Clinical Motion Analysis Databank",
  "api_url": "https://acmad.example/api/v1/",
  "auth": {
    "issuer": "https://id.acmad.example/realms/prod",
    "client_id": "prod-cli",
    "scopes": ["openid", "profile", "email", "offline_access"]
  }
}

The document is fetched unauthenticated, with a short retry on transport and 5xx failures, and honours --no-verify-tls. Unknown keys are ignored so a server can add fields without breaking already-released clients; an unrecognised schema_version is refused rather than guessed at.

Persisting tokens is only useful when the instance advertises the offline_access scope: without a refresh token the keyring cache has nothing durable to hold.

Superseded endpoint keys

api_url, realm_url and client_id predate the instance configuration document. They are still accepted so an existing acmad.yaml keeps working, but each reports a warning, since a file pointing at a stale realm should not go unnoticed.

api_url supplies the instance URL when site_url is absent, reduced to its origin (https://acmad.example/api/v1/ becomes https://acmad.example). An instance served under a path prefix needs an explicit site_url. realm_url and client_id are ignored entirely.

The --api-url, --realm-url and --client-id options have been removed; use --site-url.

Site acronym

The site acronym is authoritative: when supplied, it replaces every workbook’s site_id, including a conflicting or malformed value. Folder names are never used to infer the site. It does not rewrite a source site_patient_id, so an existing source prefix is accepted when an override is in use.

$ acmad-upload patient validate /path/to/package --site QCH
$ acmad-upload upload /path/to/package --site QCH

The site option applies to patient, diagnosis, gait-assessment, and surgery inputs. Other records inherit their destination relationship through an existing gait assessment or motion-capture session.