Skip to documentation

Guide · CLI and CI

Available

Last verified

Operate DotMock from the repository

Use machine-readable commands for discovery, authoring, safe tests, traffic inspection, state management, and webhook delivery. The CLI follows the same team isolation and approval boundaries as the dashboard and MCP tools.

In this guide

  • Authenticate without committing credentials
  • Create and configure mocks from files
  • Run side-effect-free tests in CI
  • Listen for and inspect real webhook deliveries

Prerequisites

  • The DotMock CLI installed
  • A team-scoped management credential
  • The target workspace ID in $API_ID
On this page
  1. Install, authenticate, and verify scope
  2. Discover before creating
  3. Create from a contract or prompt
  4. Configure complete endpoint behavior
  5. Run deterministic dry-runs
  6. Automate protobuf and streaming mocks
  7. Import and exercise SOAP contracts
  8. Receive and inspect webhooks
  9. Keep publish and rollback explicit

Install, authenticate, and verify scope

Install the full DotMock CLI with npm or Homebrew, then run browser login for local development. The DotMock Homebrew tap contains installation metadata for the same published CLI package; it does not expose DotMock's private product repositories. In CI, pin the npm package version, inject DOTMOCK_API_KEY from the secret store, and never write it into the repository. Use global --json when another program consumes the output.

bash
# npm
npm install --global @dotmock/cli@latest

# Homebrew (formula-only tap hosted by DotMock)
brew tap dotmock/tap https://dotmock.com/homebrew-tap.git
brew install dotmock

# Authenticate and verify either installation
dotmock --version
dotmock login
dotmock --json status
dotmock skill install --scope project --agent auto

# Pin the npm package version in repeatable CI images
npm install --global @dotmock/[email protected]

Discover before creating

List the current team APIs and search the reusable catalog before creating another provider mock. Team-scoped API keys fail closed when an API belongs to a different team.

bash
dotmock --json list apis
dotmock --json search stripe
dotmock clone stripe-payments --name "Checkout sandbox"

Create from a contract or prompt

Prefer a checked-in OpenAPI document or TypeScript contract when one exists. --from detects the format: OpenAPI or Swagger, AsyncAPI, Postman collections (v2.x), and HAR captures are accepted; Postman and HAR files are converted to OpenAPI with their recorded responses as examples. Prompt creation is useful for a new dependency, but validate the generated contract before application code depends on it.

bash
dotmock create api --name "Orders" --from openapi.yaml
dotmock create api --name "Orders" --from orders.postman_collection.json
dotmock create api --name "Orders" --from session.har
dotmock create api --name "Orders" --from src/contracts/order.ts
dotmock create api --name "Orders" --prompt "REST orders API with create, read, cancel, and provider-shaped errors"

Configure complete endpoint behavior

Use @file inputs for schemas, responses, conditions, faults, and hooks. Configure merges with existing behavior by default. Replacement and clear flags are explicit because they can remove existing outcomes.

bash
dotmock create endpoint \
  --api "$API_ID" \
  --method GET \
  --path '/orders/{id}' \
  --from endpoint.yaml

dotmock configure endpoint --api "$API_ID" --method POST --path /orders \
  --response-hook "$WEBHOOK_API_ID:order.created"

Run deterministic dry-runs

dotmock test never persists state, delivers webhooks, proxies, or executes callouts. Give CI a fixed seed and protocol-specific request files, then assert the returned winner, response, diagnostics, and state diff.

bash
dotmock --json test \
  --api "$API_ID" \
  --method GET \
  --path '/orders/ord_test_1' \
  --header 'x-test-scenario:gateway-error' \
  --seed 42

Automate protobuf and streaming mocks

Create a gRPC workspace directly from a .proto tree or descriptor set. Configure reflection and health, run safe or live unary/streaming transcripts, inspect decoded traffic, and manage encrypted TLS or mTLS upstream settings.

bash
dotmock create api --type grpc --name "Users RPC" --from proto/
dotmock grpc services --api "$API_ID"
dotmock grpc settings --api "$API_ID" --reflection on --health on
dotmock grpc test --api "$API_ID" --service users.v1.Users --method GetUser --from request.json
dotmock grpc upstream set --api "$API_ID" --from upstream.yaml

Import and exercise SOAP contracts

Import a WSDL with its adjacent XSD files, configure an operation with native XML responses and normal conditional expressions, then run an isolated or live SOAP 1.1 or SOAP 1.2 request. Traffic promotion turns a captured exchange into editable operation behavior.

bash
dotmock soap import --api "$API_ID" --from contracts/users.wsdl
dotmock soap operations --api "$API_ID"
dotmock soap configure --api "$API_ID" --operation UsersService/UsersPort/GetUser --from behavior.json
dotmock soap test --api "$API_ID" --operation UsersService/UsersPort/GetUser --from request.xml --version 1.2
dotmock soap traffic --api "$API_ID"

Receive and inspect webhooks

Keep a listener running for the webhook workspace, trigger an event, and inspect the durable delivery record. Local listeners can forward the signed request to your application on localhost.

bash
dotmock webhook listen --api "$WEBHOOK_API_ID" --forward-to http://localhost:3000/webhooks
dotmock --json webhook trigger --api "$WEBHOOK_API_ID" --event invoice.created --from invoice.json
dotmock --json webhook inspect --api "$WEBHOOK_API_ID" --limit 20

Keep publish and rollback explicit

Configuration apply and patch update the shared draft. Validate, diff, and simulate before publication. Publish, rollback, and dotmock delete api ask for confirmation in a terminal; in CI, with --json, or with piped stdin they fail fast unless you pass --yes (or --force) instead of waiting for input. Commands that take an API accept its id, subdomain, or name and suggest close matches when nothing matches.

bash
dotmock config pull --api "$API_ID" --output dotmock.yaml
dotmock config plan --api "$API_ID" --file dotmock.yaml
dotmock config apply --api "$API_ID" --file dotmock.yaml
dotmock config validate --api "$API_ID"
dotmock --json config simulate --api "$API_ID" --request @request.json --seed 42
dotmock config publish --api "$API_ID" --yes
dotmock delete api orders --yes