microcks · Caesarsage · Aug 26, 2026 · Aug 26, 2026 · Aug 26, 2026 · Aug 26, 2026
@@ -71,11 +71,18 @@ microcks [command] [flags]
 | `stop`       | Stop a local Microcks instance                           | [`stop`](documentation/cmd/stop.md)             |
 | `import`     | Import API spec files from local filesystem              | [`import`](documentation/cmd/import.md)         |
 | `import-dir`  | Scan a directory and import API spec files.              | [`import-dir`](documentation/cmd/importDir.md)     |
-| `import-url` | Import API spec files directly from a remote URL         | [`import-url`](documentation/cmd/importUrl.md) |
+| `import-url` | Import API spec files directly from a remote URL         | [`import-url`](documentation/cmd/importURL.md) |
 | `service`    | List and inspect Microcks services                       | [`service`](documentation/cmd/service.md)       |
 | `test`       | Run tests against a deployed API using selected runner   | [`test`](documentation/cmd/test.md)             |
 | `version`    | Print Microcks CLI version                               | [`version`](documentation/cmd/version.md)       |
 
+### Reference
+
+| Topic | Documentation |
+| ----- | ------------- |
+| Consuming the CLI from a script, CI job or editor extension | [JSON output contracts](documentation/json-output.md) |
+| Exit codes and the error-handling model | [Error handling](documentation/error-handling.md) |
+
 ### Options
 
 | Flag                     | Description                                 |
@@ -140,12 +147,16 @@ microcks test --dry-run --watch \
 | `--image` | `quay.io/microcks/microcks-uber:latest-native` | Uber image override (must be a `*-native` tag) |
 | `--ready-timeout` | `90s` | How long to wait for the container to be ready |
 | `--watch` | `false` | Re-run the test when the artifact file changes |
+| `--driver` | _(auto-detect)_ | Container runtime: `docker` or `podman` |
 
 Notes:
 
 - A `localhost`/`127.0.0.1` test endpoint is automatically reachable from inside the container — the CLI exposes the port and rewrites the endpoint for you.
 - The container is removed on every exit path, including `Ctrl+C` mid-test.
-- Docker is the primary runtime; Podman works through its Docker-compatible socket (`DOCKER_HOST`).
+- Without `--driver`, Podman is selected only when `DOCKER_HOST` is unset, `podman` is on the `PATH` and `docker` is not — an existing Docker or remote-daemon setup keeps working untouched. `--driver podman` verifies the Podman socket before starting the container and fails with exit code `14` when it is unreachable, instead of falling back to Docker.
+- Watch mode combined with `--output=json` emits a newline-delimited event stream — see [documentation/json-output.md](documentation/json-output.md).
+
+Full reference, including the runtime-selection rules and watch-mode behavior: [documentation/cmd/test.md](documentation/cmd/test.md).
 
 ### Building from Source
 
@@ -174,12 +185,20 @@ Binary releases for Linux, MacOS or Windows platform are available on the GitHub
 
 ### Container image
 
-The `microcks-cli` is available as a container image. So that you'd be able to easily use it from a GitLab CI or a [Tekton pipeline](https://github.com/tektoncd/pipeline). The hosting repository is on Quay.io [here](https://quay.io/repository/microcks/microcks-cli).
+The `microcks-cli` is also distributed as a container image, so you can run it from a GitLab CI job or a [Tekton pipeline](https://github.com/tektoncd/pipeline) without installing the binary. The image is hosted on the [Quay.io microcks-cli repository](https://quay.io/repository/microcks/microcks-cli).
 
-Below a sample on how to use the image without getting the CLI binary:
+To run a test using the image:
 
-```
-$ docker run -it quay.io/microcks/microcks-cli:latest microcks test 'Beer Catalog API:0.9' http://beer-catalog-impl-beer-catalog-dev.apps.144.76.24.92.nip.io/api/ POSTMAN --microcksURL=http://microcks.apps.144.76.24.92.nip.io/api/ --keycloakClientId=microcks-serviceaccount --keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1 --waitFor=8sec  --operationsHeaders='{"globals": [{"name": "x-api-key", "values": "my-values"}], "GET /beer": [{"name": "x-trace-id", "values": "xcvbnsdfghjklm"}]}'
+```sh
+docker run -it quay.io/microcks/microcks-cli:latest microcks test \
+  'Beer Catalog API:0.9' \
+  http://beer-catalog-impl-beer-catalog-dev.apps.144.76.24.92.nip.io/api/ \
+  POSTMAN \
+  --microcksURL=http://microcks.apps.144.76.24.92.nip.io/api/ \
+  --keycloakClientId=microcks-serviceaccount \
+  --keycloakClientSecret=<client-secret> \
+  --waitFor=8sec \
+  --operationsHeaders='{"globals": [{"name": "x-api-key", "values": "my-values"}], "GET /beer": [{"name": "x-trace-id", "values": "xcvbnsdfghjklm"}]}'
 ```
 
 
@@ -203,6 +222,10 @@ microcks test "Pastry API:1.0.0" http://localhost:8080/api OPEN_API_SCHEMA \
   --microcksURL=http://localhost:8585/api --output=json > result.json
 ```
 
+Other commands (`service`, `context`, `start`, `import`, `test list`, `test get`,
+`capabilities`) accept `--output json` too. Payload shapes, the dry-run event stream
+and capability detection are documented in [documentation/json-output.md](documentation/json-output.md).
+
 ### GitHub Actions
 
 With `--output=github-actions`, failures surface as `::error::` annotations,

@@ -19,7 +19,41 @@ microcks import-url https://example.com/openapi.yaml \
     --microcksURL <microcks-url> \ 
     --keycloakClientId <client-id> \
     --keycloakClientSecret <client-secret> 
+
+# Download a protected artifact using a stored Microcks secret
+microcks import-url https://example.com/openapi.yaml:true:my-secret
+
+# A port in the URL is not mistaken for a suffix
+microcks import-url http://localhost:8585/spec.yaml:false
+```
+
+### Argument syntax
+
+Each comma-separated entry is a URL optionally followed by a `mainArtifact` flag and
+a secret name:
+
 ```
+<specURL>[:<mainArtifact>[:<secretName>]]
+```
+
+| Part | Default | Description |
+| ---- | ------- | ----------- |
+| `<specURL>` | _(required)_ | `http://` or `https://` URL Microcks downloads the artifact from |
+| `<mainArtifact>` | `true` | `true` marks the artifact as primary, `false` as secondary |
+| `<secretName>` | _(none)_ | Name of a secret stored in Microcks, used to authenticate the download |
+
+Because a URL contains colons of its own, the CLI resolves the suffixes from the
+right: it scans backwards for the first segment that parses as a boolean, treats that
+segment as `mainArtifact`, and takes everything after it as the secret name. A secret
+name can therefore contain colons. The CLI applies suffix parsing only to arguments
+starting with `http://` or `https://`, and passes anything else through unchanged.
+
+### Options
+
+This command has no flags of its own — it takes only the inherited options below.
+It also has no `--output` flag, so it produces human-readable output only. See
+[JSON output contracts](../json-output.md) for the commands that do emit structured
+output.
 
 ### Options Inherited from Parent Commands
 | Flag                     | Description                                 |

@@ -52,3 +52,6 @@ summary includes `id`, `name`, `version`, and `type`, and may include
 available, `messagesMap`. Integrations should check for the
 `service.list.json` and `service.get.json` capabilities before depending on
 these contracts.
+
+See [JSON output contracts](../json-output.md) for the stream conventions and
+capability detection shared by all machine-readable commands.
@@ -36,6 +36,71 @@ microcks test get <test-result-id> --output json
 One of:
 `HTTP`|`SOAP_HTTP`|`SOAP_UI`|`POSTMAN`|`OPEN_API_SCHEMA`|`ASYNC_API_SCHEMA`|`GRPC_PROTOBUF`|`GRAPHQL_SCHEMA`
 
+### Local dry-run (ephemeral container)
+
+`--dry-run` runs the contract test without any infrastructure: no running Microcks
+server, no Keycloak credentials, no prior import. The CLI starts an ephemeral
+Microcks container, imports `--artifact`, runs the test against your endpoint,
+prints the result and tears the container down.
+
+```bash
+# One-shot: run once, tear down, exit (exit code reflects the test result)
+microcks test --dry-run \
+  --artifact ./openapi.yaml \
+  "Pastry API:1.0.0" \
+  http://localhost:3000 \
+  OPEN_API_SCHEMA
+
+# Watch mode: keep the container alive, re-import and re-run on every save
+microcks test --dry-run --watch \
+  --artifact ./openapi.yaml \
+  "Pastry API:1.0.0" \
+  http://localhost:3000 \
+  OPEN_API_SCHEMA
+```
+
+| Flag              | Default                                        | Description                                              |
+| ----------------- | ---------------------------------------------- | -------------------------------------------------------- |
+| `--dry-run`       | `false`                                        | Run against an ephemeral container instead of a server   |
+| `--artifact`      | _(required with `--dry-run`)_                  | Local spec file imported as the main artifact            |
+| `--image`         | `quay.io/microcks/microcks-uber:latest-native` | Uber image override; must be a `*-native` tag            |
+| `--ready-timeout` | `90s`                                          | How long to wait for the container to become ready       |
+| `--watch`         | `false`                                        | Re-import and re-run the test when the artifact changes  |
+| `--driver`        | _(auto-detect)_                                | Container runtime: `docker` or `podman`                  |
+
+`--artifact`, `--watch` and `--driver` are only meaningful with `--dry-run`;
+passing one without it is a usage error (exit code `2`).
+
+The command accepts only the `-native` image flavor. That variant runs without
+Keycloak, which is what makes a zero-configuration dry-run possible.
+
+#### Choosing a container runtime
+
+Without `--driver`, the CLI selects Podman only when `DOCKER_HOST` is unset, `podman`
+is on the `PATH` and `docker` is not. An explicitly configured `DOCKER_HOST` takes
+precedence, so an existing Docker or remote-daemon setup keeps working unchanged.
+
+`--driver podman` verifies the Podman socket before starting the container. When the
+socket is unreachable, the command fails with an environment error and exit code
+`14` instead of falling back to Docker. Start the socket with `podman machine start`
+on macOS and Windows, or `systemctl --user start podman.socket` on Linux.
+
+#### Dry-run behavior
+
+- A `localhost` or `127.0.0.1` test endpoint is rewritten to
+  `host.testcontainers.internal` and its port exposed to the container, so an API
+  running on your machine is reachable without any change on your side.
+- The container is removed on every exit path, including `Ctrl+C` mid-test.
+- In watch mode the CLI watches the artifact's _directory_ rather than the file.
+  Many editors save by replacing the file, which cancels a watch registered on the
+  file itself. The CLI also debounces bursts of save events.
+- A spec that is invalid while you are still editing it does not stop the session:
+  the CLI reports the failed re-import and keeps watching. The next valid save
+  recovers.
+
+Watch mode combined with `--output json` emits a newline-delimited event stream
+instead of rendered results. See [JSON output contracts](../json-output.md).
+
 ### Options
 | Flag                   | Description                                                                         |
 | ---------------------- | ----------------------------------------------------------------------------------- |
@@ -47,6 +112,9 @@ One of:
 | `--oAuth2Context`      | OAuth2 client context as JSON string                                                |
 | `--output`             | Output format: `text` (default), `json`, `yaml`, or `github-actions`                |
 
+The dry-run flags (`--dry-run`, `--artifact`, `--image`, `--ready-timeout`,
+`--watch`, `--driver`) are listed under [Local dry-run](#local-dry-run-ephemeral-container) above.
+
 ### `test list` and `test get` Options
 | Flag          | Description                                      |
 | ------------- | ------------------------------------------------ |
@@ -72,12 +140,10 @@ One of:
 
 `test list --output json` writes a JSON array of test-result summaries.
 `test get --output json` writes one complete test result, including its
-`testCaseResults` when present. Integrations should check for the
-`test.list.json` and `test.get.json` capabilities before depending on these
-contracts.
-
-`microcks test ... --output json` and one-shot dry-run tests write the completed
-test result to stdout while progress and diagnostics go to stderr. Dry-run
-watch mode writes one JSON event per line. Consumers should require
-`test.dry-run.watch.events.json` and handle `ready`, `imported`, `test-result`,
-`waiting`, `error`, and `stopped`.
+`testCaseResults` when present. `microcks test ... --output json` and one-shot
+dry-run tests write the completed test result to stdout while progress and
+diagnostics go to stderr.
+
+Field-level schemas, the newline-delimited dry-run watch events, and the
+capability identifiers to check before depending on any of them are documented in
+[JSON output contracts](../json-output.md).
@@ -0,0 +1,146 @@
+# JSON output contracts
+
+How to consume the `microcks` CLI from another program — an editor extension, a CI
+job, a script. This page is the reference for the machine-readable surface: which
+commands produce structured output, what lands on which stream, the schema of the
+dry-run event stream, and how to detect support before depending on any of it.
+
+For the human-facing description of each command, see [documentation/cmd/](cmd/).
+
+## Streams
+
+Commands render human progress on `stdout` in the default `text` mode. As soon as
+a machine-readable `--output` value is selected, progress and diagnostics move to
+`stderr` and `stdout` carries the payload alone:
+
+```bash
+microcks test "Pastry API:1.0.0" http://localhost:8080/api OPEN_API_SCHEMA \
+  --microcksURL=http://localhost:8585/api --output=json > result.json
+```
+
+`result.json` holds the test result and nothing else — no status lines to strip, no
+partial JSON. The same split applies to the dry-run path, so container startup and
+teardown messages stay out of the parsed stream.
+
+Diagnostics on stderr are written for people to read and are not a contract. Do not
+parse them.
+
+## Supported formats per command
+
+| Command | `text` | `json` | `yaml` | `github-actions` |
+| --- | :---: | :---: | :---: | :---: |
+| `test` | ✓ | ✓ | ✓ | ✓ |
+| `test list` | ✓ | ✓ | | |
+| `test get` | ✓ | ✓ | | |
+| `service list` | ✓ | ✓ | | |
+| `service get` | ✓ | ✓ | | |
+| `context` | ✓ | ✓ | | |
+| `start` | ✓ | ✓ | | |
+| `import` | ✓ | ✓ | | |
+| `capabilities` | ✓ | ✓ | | |
+
+`test` is the only command that renders a full `TestResult`, so it is the only one
+offering `yaml` and `github-actions`. Everything else exposes `text` or `json`.
+
+`import --watch` cannot be combined with `--output json`: watching is an open-ended
+interactive loop with no single result document to emit.
+
+`import-dir` and `import-url` have no `--output` flag yet. Do not expect JSON from
+them.
+
+## Payload shapes
+
+| Command | stdout on `--output json` |
+| --- | --- |
+| `test`, `test get` | One complete `TestResult` object, including `testCaseResults` when present |
+| `test list` | Array of test-result summaries |
+| `service list` | Array of service summaries — each with `id`, `name`, `version`, `type`, and possibly `operations` |
+| `service get` | Object with `service` and, when available, `messagesMap` |
+| `context` | Array of `{name, server, current}`; `[]` when no local config exists, which is a valid disconnected state |
+| `start` | `{name, server, context, status}` for the started instance |
+| `import` | Array of `{file, id, primary, action}`, one entry per imported artifact |
+| `capabilities` | `{schemaVersion, cliVersion, capabilities[]}` |
+
+## Dry-run watch events
+
+`microcks test --dry-run --watch --output json` switches to a newline-delimited
+event stream instead of rendering results. All three flags are required — with
+`--watch` but without `--output json` the run stays in human mode, and without
+`--watch` a single rendered result is written instead.
+
+One JSON object per line, so a consumer can read incrementally:
+
+```bash
+microcks test --dry-run --watch --output json \
+  --artifact ./openapi.yaml "Pastry API:1.0.0" http://localhost:3000 OPEN_API_SCHEMA \
+  | jq -c '{type, success: .result.success}'
+```
+
+### Event fields
+
+| Field | Present on | Meaning |
+| --- | --- | --- |
+| `type` | every event | One of the types below |
+| `timestamp` | every event | RFC 3339 with nanoseconds, UTC, stamped at emit |
+| `endpoint` | `ready` | HTTP endpoint of the ephemeral Microcks server |
+| `artifact` | `imported` | Path of the artifact that was imported |
+| `service` | `imported` | Service reference the artifact was imported as |
+| `testResultId` | `test-result` | Id of the completed test result |
+| `result` | `test-result` | The complete `TestResult` object |
+| `message` | `error` | Text of the underlying failure |
+
+Fields not relevant to an event type are omitted, not sent as `null`.
+
+### Event types
+
+| Type | Emitted when |
+| --- | --- |
+| `ready` | The ephemeral container is running and its endpoint is resolved |
+| `imported` | The artifact has been imported — once at startup, then after each change |
+| `test-result` | A test run completed; carries the full result |
+| `waiting` | The CLI is idle, watching for the next artifact change |
+| `error` | An import or test run failed |
+| `stopped` | The CLI is exiting |
+
+A normal session emits `ready`, `imported`, `test-result`, `waiting`, then a further
+`imported` / `test-result` / `waiting` triple per saved change, and `stopped` on exit.
+
+Two properties matter when writing a consumer:
+
+- **`error` is not terminal.** A spec that is invalid while you are still editing it
+  is expected. The CLI reports the failure and keeps watching; the next valid save
+  produces `imported` and `test-result` as usual. Treat `error` as a status to
+  display, not a reason to end your session.
+- **`stopped` is always emitted**, including on `Ctrl+C` and on the error paths, so it
+  is a reliable end-of-stream marker.
+
+## Detecting support
+
+Do not infer support from a version number. Query the CLI instead:
+
+```bash
+microcks capabilities --output json
+```
+
+```json
+{
+  "schemaVersion": "v1",
+  "cliVersion": "1.0.3",
+  "capabilities": ["service.list.json", "test.dry-run.watch.events.json", "..."]
+}
+```
+
+Check for the identifier covering the contract you are about to use — for example
+`test.dry-run.watch.events.json` before subscribing to the event stream, or
+`service.get.json` before parsing service details — and degrade gracefully when it is
+absent. The full list is in [capabilities](cmd/capabilities.md).
+
+Capabilities describe the installed binary. They say nothing about optional features
+of the Microcks server it talks to.
+
+## Exit codes
+
+A structured payload on `stdout` does not replace the exit code; both are part of the
+contract. In particular, exit code `1` means a clean run whose contract test did not
+conform, which is the tool working correctly. Codes of `2` and above mean the tool
+itself could not complete. See [error handling and exit codes](error-handling.md).