Microcks CLI

Simple CLI for interacting with Microcks server APIs. It allows launching tests or import API artifacts with minimal dependencies.

Build Status

Latest release is 1.0.3.

Current development version is 1.0.4. It is available as a container image named quay.io/microcks/microcks-cli:nightly.

Fossa license and security scans

Signature, Provenance, SBOM

OpenSSF best practices on Microcks core

Community

• Documentation
• Microcks Community and community meeting
• Join us on Discord, on GitHub Discussions or CNCF Slack #microcks channel

To get involved with our community, please make sure you are familiar with the project's Code of Conduct.

Installation

Visit the Release page, browse the Assets and download the one matching your platform

OR you can use the Homebrew package manager on Linux and MacOS that way:

brew tap microcks/tap
brew install microcks/tap/microcks

Usage instructions

Usage

microcks [command] [flags]

Available Commands

Command	Description	Documentation
login	Log in to a Microcks instance using Keycloak credentials	login
logout	Log out and remove authentication from a given context	logout
context	Manage CLI contexts (list, use, delete)	context
capabilities	List machine-readable CLI capabilities	capabilities
start	Start a local Microcks instance via Docker/Podman	start
stop	Stop a local Microcks instance	stop
import	Import API spec files from local filesystem	import
import-dir	Scan a directory and import API spec files.	import-dir
import-url	Import API spec files directly from a remote URL	import-url
service	List and inspect Microcks services	service
test	Run tests against a deployed API using selected runner	test
version	Print Microcks CLI version	version

Options

Flag	Description
-h, --help	help for microcks command
--config	Path to Microcks config file
--microcks-context	Name of the Microcks context to use
--verbose	Produce dumps of HTTP exchanges
--insecure-tls	Allow insecure HTTPS connections
--caCerts	Comma-separated paths of CA cert files
--keycloakClientId	Keycloak Realm Service Account ClientId
--keycloakClientSecret	Keycloak Realm Service Account ClientSecret
--microcksURL	Microcks API URL

Exit codes

microcks returns a distinct exit code per outcome, so CI can branch on why a run failed — for example retry a flaky runner but fail the build on a broken contract:

Code	Meaning
0	Success, or the contract test conformed
1	Contract test failed — a clean run whose result did not conform
2	Usage — bad arguments or flags
11	Connection — could not reach the Microcks or Keycloak endpoint
12	API — a server rejected the request or returned an unusable response
13	Not found — a requested resource does not exist
14	Environment — a local precondition failed (container runtime, image, readiness)
20	Generic — an unclassified failure

1 means the tool ran fine and the API violated its contract — not that the tool errored. Codes 0/1/2 follow the common Unix exit-status convention; 11–20 are Microcks-CLI–specific. See documentation/error-handling.md.

Local contract testing without a server

microcks test --dry-run runs a contract test with zero infrastructure: no running Microcks server, no Keycloak credentials, no upfront import. The CLI spins up an ephemeral Microcks container (via Testcontainers), imports your spec, runs the test against your endpoint, prints the result and tears the container down.

# One-shot: run once, tear down, exit (exit code 0/1 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 + re-run on every save (TDD loop)
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	Activate the ephemeral-container path
--artifact	(required with --dry-run)	Local spec file imported as 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 be ready
--watch	false	Re-run the test when the artifact file changes

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).

Building from Source

To build the CLI locally:

make build-local

The resulting binary will be available at:

/build/dist/microcks

You can move it to a location in your $PATH for global usage, for example:

sudo mv build/dist/microcks /usr/local/bin/microcks

Binary

Binary releases for Linux, MacOS or Windows platform are available on the GitHub releases page. Just download the binary corresponding to your system and put the binary into the PATH somewhere ;-)

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. The hosting repository is on Quay.io here.

Below a sample on how to use the image without getting the CLI binary:

$ 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"}]}'

Machine-readable test output

microcks test accepts --output to control how the result is rendered:

Value	Output
text (default)	Human-readable summary
json	The full TestResult as JSON
yaml	The full TestResult as YAML
github-actions	GitHub Actions workflow commands (annotations + log groups + step summary)

For machine formats (json/yaml/github-actions), progress goes to stderr and only the formatted result is written to stdout, so it can be piped or parsed cleanly:

microcks test "Pastry API:1.0.0" http://localhost:8080/api OPEN_API_SCHEMA \
  --microcksURL=http://localhost:8585/api --output=json > result.json

GitHub Actions

With --output=github-actions, failures surface as ::error:: annotations, each operation is wrapped in a collapsible ::group::, and a per-operation table is appended to the job summary ($GITHUB_STEP_SUMMARY). Set MICROCKS_ACTIONS_VERBOSE=true to also emit ::notice:: for passing operations.

# .github/workflows/contract-test.yml
name: contract-test
on: [pull_request]
jobs:
  contract-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Microcks contract test
        run: |
          microcks test "Pastry API:1.0.0" "${{ env.API_URL }}" OPEN_API_SCHEMA \
            --microcksURL=${{ secrets.MICROCKS_URL }} \
            --keycloakClientId=${{ secrets.MICROCKS_CLIENT_ID }} \
            --keycloakClientSecret=${{ secrets.MICROCKS_CLIENT_SECRET }} \
            --output=github-actions

Tekton tasks

This repository also contains different Tekton tasks definitions and sample pipelines. You'll find under the /tekton folder the resource for current v1beta1 Tekton API version and the older v1alpha1 under tekton/v1alpha1.