FHIR Frog Tool Reference¶

This page is generated from the live FHIR Frog tool registry (docs/tools-inventory.json) and lists every tool available in v0.1. All parameters are listed with their real names (including confirm, serverUrl, fixturesPath, etc.). Do not use parameters not listed here.

Tool list¶

Environment & Setup¶

Tool	Purpose
`frog_doctor`	Run environment health checks (Docker, Java, ports, packages)
`frog_check_ig`	Check an IG for publishing traps

Package Management¶

Tool	Purpose
`frog_package_list`	List locally-available FHIR packages
`frog_package_install`	Extract a test package from frog-runner to local cache

Authoring & Validation (IG developer)¶

Tool	Purpose
`frog_scaffold_ig`	Create a new IG or retrofit tests into an existing one
`frog_scaffold_test_ig`	Create a standalone Test IG package
`frog_tsh_validate`	Validate TSH shorthand syntax
`frog_tsh_compile`	Compile TSH to JSON TestScript
`frog_testscript_lint`	Lint a TestScript for required fields and references

Server Management¶

Tool	Purpose
`frog_server_list`	List registered servers
`frog_server_register`	Register a FHIR server
`frog_server_describe`	Show details of a registered server
`frog_server_spec_list`	List available server specifications (conformance profiles)
`frog_server_check`	Verify a server is running and responsive
`frog_server_start_local`	Start a local HAPI FHIR server in Docker
`frog_server_stop`	Stop a local server

Running Tests¶

Tool	Purpose
`frog_run_local`	Run tests locally (in-process)
`frog_run_remote`	Submit tests to frog-runner
`frog_run_status`	Poll the status of a remote run
`frog_runner_start_local`	Start a local frog-runner in Docker
`frog_runner_stop`	Stop the local runner

Reports & Results¶

Tool	Purpose
`frog_report_summarise`	Compact summary of a test run
`frog_run_report`	Download a report in various formats

Key parameters¶

These parameters appear in multiple tools:

Authentication¶

authType: NONE (default), BEARER_TOKEN, or CLIENT_CREDENTIALS
bearerToken: ${ENV_VAR} reference for a Bearer token
tokenUrl: OAuth2 token endpoint (required for CLIENT_CREDENTIALS)
clientId: OAuth2 client id
clientSecret: ${ENV_VAR} reference for the client secret
scope: OAuth2 scope string

Note: Never pass actual secrets in parameters; use ${ENV_VAR} references. The user sets environment variables themselves.

Server targeting¶

serverUrl: Direct FHIR server URL (e.g. http://localhost:8080/fhir)
server: Registered backend name (from ~/.fhir-frog/backends.yaml)
spec: Server-spec id (e.g. au-core, for canonical lookup)

Resolution order: serverUrl > server > spec.

Files & paths¶

scriptPath: Path to a TestScript (.json, .xml, .tsh)
fixturesPath: Directory where fixture files are located
bundlePath: Path to a TestScript bundle directory
outputPath: Where to write output (workspace-relative)

Confirmation¶

confirm: true to perform side effects (start containers, write files, run against non-loopback servers)

When confirm is absent or false, tools return a plan without acting.

Timeouts¶

timeoutSeconds: Maximum time for this call (default 90, max 110)
pollIntervalSeconds: How often to poll for updates (default 3)

Detailed reference¶

frog_doctor¶

Checks your environment: Docker, Java, Maven, ports, FHIR packages, authoring tools.

Parameters: - ports (optional): List of ports to check for availability (default: [8080, 8081])

Example:

frog_doctor()
frog_doctor(ports=[9000, 9001])

frog_package_list¶

List packages in the local FHIR package cache and/or in frog-runner.

Parameters: - includeRunner (optional): Query frog-runner too (default: false) - runnerUrl (optional): Override FROG_RUNNER_URL

Example:

frog_package_list()
frog_package_list(includeRunner=true)

frog_package_install¶

Extract a test package from frog-runner into ~/.fhir/packages.

Parameters: - packageId (required): e.g. fhirfrog.au-core-tests - version (required): Concrete version (e.g. 0.1.0); #dev and #current not allowed - confirm (optional): Set to true to perform - image (optional): Override the source image

Example:

frog_package_install(
  packageId: "fhirfrog.au-core-tests",
  version: "0.1.0",
  confirm: true
)

frog_tsh_validate¶

Validate TestScript Shorthand (.tsh) syntax.

Parameters: - path (required): Path to a .tsh file

Example:

frog_tsh_validate(path: "my-test.tsh")

frog_tsh_compile¶

Compile TSH to JSON TestScript.

Parameters: - path (required): Path to a .tsh file - output (required): Output path for the JSON TestScript

Example:

frog_tsh_compile(path: "my-test.tsh", output: "my-test.json")

frog_testscript_lint¶

Lint a TestScript for required fields and references.

Parameters: - path (optional): Path to a JSON/XML TestScript (workspace-relative) - json (optional): Inline TestScript JSON string. Use path or json, not both. - igPackageAvailable (optional): Whether an IG package is configured (default: false)

Example:

frog_testscript_lint(path: "my-test.json")

frog_scaffold_ig¶

Create or retrofit an IG with test infrastructure.

Parameters: - dir (required): New or existing IG directory - mode (required): new or retrofit - packageId (required for new) - canonical (required for new) - name (required for new) - title (required for new) - publisher (required for new) - subjectIg (required for new; e.g. hl7.fhir.au.core#2.0.0) - fhirVersion (optional): Default 4.0.1 - version (optional): Default 0.1.0 - ci (optional): gitlab, github, or none (default) - confirm (optional): Set to true to write

Example:

# Create a new IG with tests
frog_scaffold_ig(
  dir: "my-ig",
  mode: "new",
  packageId: "my.ig",
  canonical: "http://example.org/my-ig",
  name: "MyIG",
  title: "My Implementation Guide",
  publisher: "Example Org",
  subjectIg: "hl7.fhir.au.core#2.0.0",
  confirm: true
)

# Retrofit an existing IG
frog_scaffold_ig(
  dir: "my-existing-ig",
  mode: "retrofit",
  confirm: true
)

frog_server_list¶

List all registered servers.

Parameters: None

Example:

frog_server_list()

frog_server_register¶

Parameters: - name (required): Nickname - url (required): Server URL - conformsTo (optional): Implementation guide id#version - confirm (optional): Set to true to register

Example:

frog_server_register(
  name: "my-server",
  url: "http://localhost:8080/fhir",
  conformsTo: "http://example.org/ImplementationGuide/au-core#2.0.0",
  confirm: true
)

frog_server_check¶

Verify a server is responding.

Parameters: - name (optional): Server name (if registered) - url (optional): Server URL (if not registered)

Example:

frog_server_check(name: "my-server")
frog_server_check(url: "http://localhost:8080/fhir")

frog_server_start_local¶

Start a local HAPI FHIR server in Docker. Note: this starts plain HAPI without any IG preloaded. To use an IG-aware server, either use an IG-aware image or point to a server that already has the IG loaded.

Parameters: - port (optional): Host port (default: 8081) - image (optional): Override the HAPI image; only hapiproject/hapi images are accepted here. To use your own image (for example one that bundles your IG) set the FROG_SUT_IMAGE environment variable for the MCP server instead - confirm (optional): Set to true to start

Example:

frog_server_start_local(port: 8081, confirm: true)

frog_server_stop¶

Stop a local server.

Parameters: - confirm (optional): Set to true to stop

frog_run_local¶

Run tests locally (in-process).

Parameters: - scriptPath (optional): Path to TestScript (.json/.xml/.tsh) - testPackage (optional): Test package id#version - serverUrl (optional): Server URL - server (optional): Registered server name - spec (optional): Server-spec id - fixturesPath (optional): Fixture directory - igPackage (optional): IG package id#version (for profile validation) - terminologyServerUrl (optional): Terminology server URL - authType (optional): NONE, BEARER_TOKEN, or CLIENT_CREDENTIALS - bearerToken (optional): ${ENV_VAR} reference (if authType=BEARER_TOKEN) - tokenUrl (optional): Token endpoint (if authType=CLIENT_CREDENTIALS) - clientId (optional): OAuth2 client id - clientSecret (optional): ${ENV_VAR} reference - scope (optional): OAuth2 scope - confirm (optional): Set to true for non-loopback servers - timeoutSeconds (optional): Max wait (default 90, max 110)

Example:

frog_run_local(
  scriptPath: "my-test.json",
  serverUrl: "http://localhost:8080/fhir"
)

frog_run_local(
  scriptPath: "my-test.json",
  server: "my-server",
  igPackage: "hl7.fhir.au.core#2.0.0"
)

frog_run_remote¶

Run tests via frog-runner (remote or local).

Parameters: - testPackage (optional): Test package id#version (e.g. fhirfrog.au-core-tests#0.1.0). Mutually exclusive with bundlePath. - bundlePath (optional): Path to a TestScript bundle directory on the runner side. Mutually exclusive with testPackage. - serverUrl (optional): Server URL - server (optional): Registered server name - spec (optional): Server-spec id - igPackage (optional): IG package id#version - terminologyServerUrl (optional): Terminology server URL - runnerUrl (optional): Override FROG_RUNNER_URL - confirm (optional): Set to true for non-loopback servers - timeoutSeconds (optional): Max wait (default 90, max 110) - pollIntervalSeconds (optional): Polling interval (default 3)

Note: frog_run_remote submits to the runner and takes a package (testPackage) or a bundle directory (bundlePath). To run a single TestScript .json file locally, use frog_run_local(scriptPath=...) instead.

Example:

frog_run_remote(
  testPackage: "fhirfrog.au-core-tests#0.1.0",
  serverUrl: "http://localhost:8080/fhir"
)

frog_run_remote(
  testPackage: "fhirfrog.au-core-tests#0.1.0",
  server: "my-server",
  runnerUrl: "http://127.0.0.1:8080"
)

frog_run_status¶

Poll the status of a remote run.

Parameters: - runId (required): Run ID returned by frog_run_remote - runnerUrl (optional): Override FROG_RUNNER_URL

Example:

frog_run_status(runId: "run-abc123")

frog_runner_start_local¶

Start a local frog-runner in Docker.

Parameters: - port (optional): Host port (default: 8080) - bundlePath (optional): Path to bundle directory - confirm (optional): Set to true to start - image (optional): Override the image

Example:

frog_runner_start_local(confirm: true)
frog_runner_start_local(port: 8080, confirm: true)

frog_runner_stop¶

Stop the local frog-runner.

Parameters: - confirm (optional): Set to true to stop

frog_report_summarise¶

Produce a compact summary of a test run.

Parameters: - runId (optional): Run ID from frog_run_remote - reportPath (optional): Path to a saved run.json - runnerUrl (optional): Override FROG_RUNNER_URL

Example:

frog_report_summarise(runId: "run-abc123")
frog_report_summarise(reportPath: "run.json")

frog_run_report¶

Download a test report in various formats.

Parameters: - runId (required): Run ID - format (required): xlsx, csv, md, pdf, docx, testreport-json, testreport-xml, junit-xml - outputPath (optional): Where to save (workspace-relative) - runnerUrl (optional): Override FROG_RUNNER_URL

Example:

frog_run_report(
  runId: "run-abc123",
  format: "junit-xml",
  outputPath: "reports/results.xml"
)

Error handling¶

Every tool error is structured as:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable message",
    "hint": "How to fix it",
    "details": "Optional technical details"
  }
}

Common error codes: needs_confirmation, docker_unavailable, network_error, parse_error, not_found, name_conflict, timeout.

See skill/fhir-frog/references/troubleshooting.md for a complete list.

Argument	Type	Description
`build`	string	Build tool to generate wiring for: maven, ant, or publisher.
`dir`	string	Relative path within workspace to the project directory.
`serverUrl`	string	FHIR server URL (default: http://localhost:8080/fhir).
`testScript`	string	Path to a TestScript file (used in snippet).
`testPackage`	string	Test IG package id#version (used in snippet).
`fixturesPath`	string	Fixture base path (default: fixtures).
`reportDir`	string	Report output directory (default: target/fhir-reports).
`igPackage`	string	igPackage id#version for testPackage mode.
`terminologyServer`	string	Terminology server URL.
`confirm`	boolean	If true, apply the snippet to the existing pom.xml/build.xml. Default false.

FHIR Frog Tool Reference¶

Tool list¶

Environment & Setup¶

Package Management¶

Authoring & Validation (IG developer)¶

Server Management¶

Running Tests¶

Reports & Results¶

Key parameters¶

Authentication¶

Server targeting¶

Files & paths¶

Confirmation¶

Timeouts¶

Detailed reference¶

frog_doctor¶

frog_package_list¶

frog_package_install¶

frog_tsh_validate¶

frog_tsh_compile¶

frog_testscript_lint¶

frog_scaffold_ig¶

frog_server_list¶

frog_server_register¶

frog_server_check¶

frog_server_start_local¶

frog_server_stop¶

frog_run_local¶

frog_run_remote¶

frog_run_status¶

frog_runner_start_local¶

frog_runner_stop¶

frog_report_summarise¶

frog_run_report¶

Error handling¶

See also¶

`frog_wire_build`¶

FHIR Frog Tool Reference¶

Tool list¶

Environment & Setup¶

Package Management¶

Authoring & Validation (IG developer)¶

Server Management¶

Running Tests¶

Reports & Results¶

Key parameters¶

Authentication¶

Server targeting¶

Files & paths¶

Confirmation¶

Timeouts¶

Detailed reference¶

frog_doctor¶

frog_package_list¶

frog_package_install¶

frog_tsh_validate¶

frog_tsh_compile¶

frog_testscript_lint¶

frog_scaffold_ig¶

frog_server_list¶

frog_server_register¶

frog_server_check¶

frog_server_start_local¶

frog_server_stop¶

frog_run_local¶

frog_run_remote¶

frog_run_status¶

frog_runner_start_local¶

frog_runner_stop¶

frog_report_summarise¶

frog_run_report¶

Error handling¶

See also¶

frog_wire_build¶

`frog_wire_build`¶