CLI Reference

What is the CVT CLI?

The CVT CLI lets you validate contracts locally without running a server. Use it for:

Quick one-off validations during development
CI/CD pipelines that need schema comparison
Generating test fixtures from OpenAPI schemas
Starting a CVT server for remote validation

Installation

# Build from source
go build -o cvt ./cmd/cvt

# Or install globally
go install github.com/sahina/cvt/cmd/cvt@latest

Commands Overview

Command	Description
`validate`	Validate an interaction against a schema
`compare`	Compare schemas for breaking changes
`generate`	Generate test fixtures from schemas
`can-i-deploy`	Check deployment safety against registered consumers
`wait`	Wait for CVT server to become ready
`register-schema`	Register an OpenAPI schema with the server
`serve`	Start the server
`version`	Show version information

validate

Validate an HTTP request/response interaction against an OpenAPI schema.

Usage

cvt validate --schema <path> [options]

Options

Flag	Short	Description	Required
`--schema`	`-s`	Path or URL to OpenAPI schema (JSON/YAML)	Yes
`--interaction`	`-i`	Path to combined interaction JSON file	No (alternative to request/response)
`--request`		Path to request JSON file	No (use with --response)
`--response`		Path to response JSON file	No (use with --request)
`--method`	`-m`	HTTP method (GET, POST, etc.)	No (alternative to files)
`--path`	`-p`	Request path (e.g., /pets/123)	No (use with --method)
`--request-body`		Request body as JSON string	No
`--status-code`		Response status code (default: 200)	No
`--response-body`		Response body as JSON string	No
`--json`		Output results as JSON	No

Input Methods

You can provide interaction data in three ways:

1. Combined interaction file:

cvt validate --schema ./openapi.json --interaction interaction.json

2. Separate request/response files:

cvt validate --schema ./openapi.json --request req.json --response resp.json

3. Command-line flags (for simple cases):

cvt validate --schema ./openapi.json \
  --method GET --path /pets/123 \
  --status-code 200 --response-body '{"id": 123, "name": "doggie"}'

4. Using a URL for the schema:

cvt validate --schema https://petstore3.swagger.io/api/v3/openapi.json \
  --interaction interaction.json

Request File Format

{
  "method": "GET",
  "path": "/pets/123",
  "headers": {
    "Accept": "application/json"
  },
  "body": null
}

Response File Format

{
  "status_code": 200,
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"id\": 123, \"name\": \"doggie\"}"
}

Interaction File Format

{
  "request": {
    "method": "GET",
    "path": "/pets/123",
    "headers": { "Accept": "application/json" }
  },
  "response": {
    "statusCode": 200,
    "headers": { "Content-Type": "application/json" },
    "body": { "id": 123, "name": "doggie" }
  }
}

Exit Codes

Code	Meaning
0	Validation passed
1	Validation failed (errors printed)

compare

Compare two OpenAPI schema versions to detect breaking changes.

Usage

cvt compare --old <path> --new <path> [options]

Options

Flag	Description	Required
`--old`	Path or URL to old/previous schema	Yes
`--new`	Path or URL to new schema	Yes
`--json`	Output results as JSON	No

Examples

# Compare schemas
cvt compare --old ./v1/openapi.json --new ./v2/openapi.json

# JSON output for CI/CD integration
cvt compare --old ./v1/openapi.json --new ./v2/openapi.json --json

# Compare local schema against a remote URL
cvt compare --old ./local-schema.json --new https://api.example.com/openapi.json

Output

✗ Found 2 breaking change(s):

  [ENDPOINT_REMOVED] DELETE /users/{id} was removed
    Old: DELETE /users/{id}

  [REQUIRED_FIELD_ADDED] Required field 'phone' added to POST /users request
    New: phone (required)

Exit Codes

Code	Meaning
0	Schemas are compatible
1	Breaking changes detected

generate

Generate test fixtures from an OpenAPI schema.

Usage

cvt generate --schema <path> [options]

Options

Flag	Short	Description	Default
`--schema`	`-s`	Path or URL to OpenAPI schema	(required)
`--list`	`-l`	List all available endpoints and exit	false
`--method`	`-m`	HTTP method (GET, POST, PUT, DELETE, etc.)	(required for gen)
`--path`	`-p`	API path (e.g., `/users`, `/users/{id}`)	(required for gen)
`--output-type`	`-t`	What to generate: `fixture`, `request`, `response`	`fixture`
`--status-code`		Response status code (0 = first successful)	0
`--use-examples`		Use schema examples when available	true
`--content-type`		Content type for request/response	application/json
`--output`	`-o`	Output file path (default: stdout)	stdout

Examples

# List all endpoints in the schema
cvt generate --schema ./openapi.json --list

# List endpoints from a remote URL
cvt generate --schema https://petstore3.swagger.io/api/v3/openapi.json --list

# Generate complete request/response fixture
cvt generate --schema ./openapi.json --method GET --path /pets/{petId}

# Generate only request body
cvt generate --schema ./openapi.json --method POST --path /pets --output-type request

# Generate response with specific status code
cvt generate --schema ./openapi.json --method GET --path /pets --output-type response --status-code 200

# Save output to file
cvt generate --schema ./openapi.json --method GET --path /pets/{petId} -o fixture.json

Output (Fixture)

{
  "request": {
    "method": "GET",
    "path": "/pets/123",
    "headers": {
      "Accept": "application/json"
    }
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "id": 123,
      "name": "doggie",
      "status": "available"
    }
  }
}

Endpoint List Output

Available endpoints:
  GET /pets
  GET /pets/{petId}
  POST /pets
  PUT /pets/{petId}
  DELETE /pets/{petId}

can-i-deploy

Check if a schema version can be safely deployed without breaking registered consumers.

Usage

cvt can-i-deploy --schema <id> --version <version> --env <environment> [options]

Options

Flag	Description	Required	Default
`--schema`	Schema ID to check	Yes
`--version`	New version to deploy	Yes
`--env`	Target environment (dev, staging, prod)	Yes
`--server`	CVT server address	No	localhost:9550
`--json`	Output results as JSON	No	false
`--timeout`	Connection timeout in seconds	No	30

Examples

# Check deployment safety against local server
cvt can-i-deploy --schema petstore --version 2.0.0 --env prod

# Check against a remote server
cvt can-i-deploy --schema petstore --version 2.0.0 --env prod --server cvt.internal:9550

# JSON output for CI/CD
cvt can-i-deploy --schema petstore --version 2.0.0 --env prod --json

# Custom timeout
cvt can-i-deploy --schema petstore --version 2.0.0 --env prod --timeout 60

Output (Safe)

Deployment Safety Check
=======================
Schema:      petstore
Version:     2.0.0
Environment: prod

✅ SAFE TO DEPLOY

No breaking changes detected that would affect registered consumers.

Output (Unsafe)

Deployment Safety Check
=======================
Schema:      petstore
Version:     2.0.0
Environment: prod

❌ UNSAFE TO DEPLOY

Breaking changes in v2.0.0:
  - ENDPOINT_REMOVED: DELETE /pets/{petId}
    Endpoint was removed from the API

Affected consumers in prod:
├── order-service v2.1.0
│   Schema version: 1.0.0
│   Impact: BREAKING
│   Affected by:
│     - DELETE /pets/{petId}
│
└── billing-service v1.0.0
    Schema version: 1.0.0
    Impact: None

Safe consumers:     1/2
Affected consumers: 1/2

Recommendation: Coordinate with order-service team before deploying.

Exit Codes

Code	Meaning
0	Safe to deploy
1	Unsafe to deploy (breaking changes affect consumers)

wait

Wait for the CVT server to become ready. Useful for CI/CD pipelines and startup scripts.

Usage

cvt wait [options]

Options

Flag	Short	Description	Default
`--server`	`-S`	CVT server address	localhost:9550
`--timeout`	`-t`	Timeout in seconds	60
`--interval`	`-i`	Polling interval in seconds	2
`--json`	`-j`	Output results as JSON	false
`--quiet`	`-q`	Suppress output except errors	false

Examples

# Wait with defaults (60s timeout, 2s interval)
cvt wait

# Wait for specific server with custom timeout
cvt wait --server cvt.internal:9550 --timeout 120

# Custom polling interval
cvt wait --server localhost:9550 --timeout 120 --interval 1

# Short flags
cvt wait -S localhost:9550 -t 120 -i 1

# Quiet mode for CI/CD
cvt wait -q

# JSON output for scripting
cvt wait --json

Exit Codes

Code	Meaning
0	Server is ready
1	Timeout waiting for server

register-schema

Register an OpenAPI schema with the CVT server. Supports both local files and URLs, and can check for breaking changes before registering.

Usage

cvt register-schema <schema-id> <schema-file> [options]

Arguments

Argument	Description	Required
`schema-id`	Unique identifier for the schema	Yes
`schema-file`	Path or URL to OpenAPI schema (JSON/YAML)	Yes

Options

Flag	Short	Description	Default
`--version`	`-v`	Schema version (e.g., "2.0.0")
`--server`	`-S`	CVT server address	localhost:9550
`--check-compatibility`		Check for breaking changes	false
`--fail-on-breaking`		Exit with error if breaking changes	false
`--owner`		Schema owner name
`--team`		Team name
`--json`	`-j`	Output results as JSON	false
`--quiet`	`-q`	Suppress output except errors	false
`--timeout`	`-t`	Connection timeout in seconds	30

Examples

# Basic registration from file
cvt register-schema my-api ./openapi.yaml

# Register from URL
cvt register-schema my-api https://api.example.com/openapi.json

# Register with version
cvt register-schema my-api ./openapi.yaml --version 2.0.0

# Short flag for version
cvt register-schema my-api ./openapi.yaml -v 2.0.0

# Check for breaking changes before registering
cvt register-schema my-api ./openapi.yaml --check-compatibility

# Fail CI if breaking changes detected
cvt register-schema my-api ./openapi.yaml --check-compatibility --fail-on-breaking

# With ownership metadata
cvt register-schema my-api ./openapi.yaml --owner "Jane Doe" --team "Platform"

# JSON output for scripting
cvt register-schema my-api ./openapi.yaml --json

# Quiet mode
cvt register-schema my-api ./openapi.yaml -q

Exit Codes

Code	Meaning
0	Schema registered successfully
1	Registration failed or breaking changes found

serve

Start the CVT gRPC server.

Usage

cvt serve [options]

Options

Flag	Short	Description	Default
`--port`	`-p`	gRPC server port	9550
`--metrics-port`		Prometheus metrics port	9551
`--tls`		Enable TLS	false
`--cert`		Path to TLS certificate
`--key`		Path to TLS private key
`--api-key-auth`		Enable API key authentication	false

Examples

# Start with defaults
cvt serve

# Custom ports
cvt serve --port 9550 --metrics-port 9551

# Enable TLS
cvt serve --tls --cert ./certs/server.crt --key ./certs/server.key

# Enable API key authentication
cvt serve --api-key-auth

Environment Variables

The serve command also respects environment variables. See Configuration Reference for the complete list.

version

Display version information.

Usage

cvt version

Output

CVT version 1.0.0
  Commit:  abc1234
  Built:   2024-01-15T10:30:00Z

Global Options

These options work with all commands:

Flag	Description
`--help`, `-h`	Show help for command

CI/CD Integration

GitHub Actions

- name: Check for breaking changes
  run: |
    cvt compare --old ./main-schema.json --new ./pr-schema.json --json
    if [ $? -ne 0 ]; then
      echo "Breaking changes detected!"
      exit 1
    fi

- name: Check deployment safety
  run: |
    cvt can-i-deploy \
      --schema my-api \
      --version ${{ github.sha }} \
      --env prod \
      --server ${{ secrets.CVT_SERVER }} \
      --json > deploy-check.json

    if [ "$(jq '.safe_to_deploy' deploy-check.json)" != "true" ]; then
      echo "Unsafe to deploy!"
      jq '.affected_consumers' deploy-check.json
      exit 1
    fi

GitLab CI

check-breaking-changes:
  script:
    - cvt compare --old $CI_MERGE_REQUEST_TARGET_BRANCH_SHA:openapi.json --new ./openapi.json --json
  allow_failure: false
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - openapi.json

deployment-safety:
  script:
    - cvt can-i-deploy --schema $SCHEMA_ID --version $CI_COMMIT_SHA --env prod --json
  allow_failure: false

API Reference - gRPC API details
Configuration Reference - Environment variables
Breaking Changes Guide - Understanding schema compatibility

What is the CVT CLI?​

Installation​

Commands Overview​

validate​

Usage​

Options​

Input Methods​

Request File Format​

Response File Format​

Interaction File Format​

Exit Codes​

compare​

Usage​

Options​

Examples​

Output​

Exit Codes​

generate​

Usage​

Options​

Examples​

Output (Fixture)​

Endpoint List Output​

can-i-deploy​

Usage​

Options​

Examples​

Output (Safe)​

Output (Unsafe)​

Exit Codes​

wait​

Usage​

Options​

Examples​

Exit Codes​

register-schema​

Usage​

Arguments​

Options​

Examples​

Exit Codes​

serve​

Usage​

Options​

Examples​

Environment Variables​

version​

Usage​

Output​

Global Options​

CI/CD Integration​

GitHub Actions​

GitLab CI​

Related Documentation​

What is the CVT CLI?

Installation

Commands Overview

validate

Usage

Options

Input Methods

Request File Format

Response File Format

Interaction File Format

Exit Codes

compare

Usage

Options

Examples

Output

Exit Codes

generate

Usage

Options

Examples

Output (Fixture)

Endpoint List Output

can-i-deploy

Usage

Options

Examples

Output (Safe)

Output (Unsafe)

Exit Codes

wait

Usage

Options

Examples

Exit Codes

register-schema

Usage

Arguments

Options

Examples

Exit Codes

serve

Usage

Options

Examples

Environment Variables

version

Usage

Output

Global Options

CI/CD Integration

GitHub Actions

GitLab CI

Related Documentation