Skip to documentation

Guide · CLI and CI

Available

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 versioned DotMock CLI package from this site, then run login for local development. In CI, 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 install -g https://dotmock.com/downloads/dotmock-0.1.1.tgz
dotmock --version
dotmock login
dotmock --json status
dotmock skill install --scope project --agent auto

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. 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 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 and rollback require explicit authorization and a force flag; state resets, restores, and destructive actions require the same care.

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