CLI Reference

All commands support --output-format json for programmatic consumption, --output-format markdown for rich markdown output (e.g. CI comments), -v / --verbose for debug-level logging, and --help for detailed usage.

Table of contents

Global flags 

      --config string          config file path
  -h, --help                   help for pacto
      --no-cache               disable OCI bundle cache
      --output-format string   output format (text, json, markdown) (default "text")
  -v, --verbose                enable verbose output

OCI version resolution

All commands that accept oci:// references support automatic version resolution. When a reference omits the tag (e.g. oci://ghcr.io/acme/svc-pacto instead of oci://ghcr.io/acme/svc-pacto:1.0.0), pacto queries the registry for available tags and selects the highest semver version.

For dependency references declared with a compatibility constraint, only tags satisfying the constraint are considered. For example, a dependency with compatibility: "^2.0.0" and available tags 1.0.0, 2.0.0, 2.3.0, 3.0.0 resolves to 2.3.0.

Non-semver tags (e.g. latest, main) are ignored during resolution. Digest-pinned references (@sha256:...) and explicitly tagged references are used as-is.

pacto dashboard

Launches a contract exploration dashboard that aggregates data from all available sources (local filesystem, Kubernetes, OCI registries, disk cache).

The dashboard is the exploration and observability layer of the Pacto system. It visualizes the same contracts the CLI manages and the operator verifies — dependency graphs, version history, interfaces, configuration schemas, diffs, and runtime compliance — in a single unified view.

Sources are auto-detected at startup:

  • local: enabled if pacto.yaml is found in the working directory
  • k8s: enabled if a valid kubeconfig is found and the cluster is reachable
  • oci: enabled if –repo is specified, or auto-discovered from K8s imageRefs
  • cache: enabled if ~/.cache/pacto/oci contains cached bundles

When running alongside the Kubernetes operator, OCI repositories are automatically discovered from the imageRef fields of Pacto CRD resources. This provides full contract bundles, version history, interfaces, and diffs — without needing explicit –repo flags. The result is a hybrid view: runtime truth from the operator combined with contract truth from OCI.

Services are grouped by name across sources and merged using priority rules:

  • Kubernetes for runtime state (phase, checks, endpoints)
  • OCI/cache for contract content and version history
  • Local for in-progress contract changes
pacto dashboard [dir] [flags]

Examples:

  # Start dashboard with auto-detected sources
  pacto dashboard

  # Start from a specific directory
  pacto dashboard ./services

  # Include OCI repositories
  pacto dashboard --repo ghcr.io/org/order-service --repo ghcr.io/org/payment-service

  # Custom port
  pacto dashboard --port 9090

  # Specify Kubernetes namespace (default: all namespaces)
  pacto dashboard --namespace production

Flags:

      --diagnostics        enable source diagnostics panel in the dashboard UI
  -h, --help               help for dashboard
      --host string        bind address for the dashboard server (default "127.0.0.1")
      --namespace string   Kubernetes namespace (empty = all namespaces)
      --port int           port for the dashboard server (default 3000)
      --repo stringArray   OCI repository to scan (can be repeated)

The dashboard is the exploration and observability layer of the Pacto system. It visualizes the same contracts the CLI manages and the operator verifies — making dependency graphs, version history, interfaces, configuration schemas, and diffs accessible in one place.

What the dashboard shows

  • Dependency graphs — interactive D3 visualization of service relationships, with impact chain highlighting
  • Version history — all available versions from OCI, with the ability to fetch and cache every version
  • Interface details — OpenAPI endpoints, gRPC definitions, event schemas extracted from contract bundles
  • Configuration schemas — JSON Schema properties for environment variables and settings
  • Policy references — organizational standards enforcement via referenced policy contracts
  • Diffs between versions — classified changes (breaking, non-breaking, potential) between any two versions
  • Runtime compliance — when Kubernetes is available, live phase, conditions, endpoint health, and contract-vs-runtime comparison

Contract-first resolution

Sources are resolved using a contract-first model. Contract sources (local, oci) provide the authoritative service definition — exactly one contract snapshot wins per service, with local taking priority over oci. The runtime source (k8s) enriches the contract with live cluster state (phase, conditions, endpoints) but never overrides contract content.

Kubernetes + OCI hybrid view

When running alongside the Kubernetes operator (no --repo flags needed), the dashboard automatically discovers OCI repositories from the imageRef fields in Pacto CRD statuses. This means a K8s-only dashboard deployment gets the full contract experience: version history, interface details, configuration schemas, and diffs — all loaded from OCI and merged with runtime state from the operator.

Dependency resolution

When OCI repository names differ from contract service names (e.g., repo my-service-pacto but contract has service.name: my-service), the dashboard automatically builds a ref-alias map from imageRef and chartRef fields so that dependency links, graph edges, and cross-references resolve correctly.

Graph visualization

The built-in D3 force-directed graph supports:

  • Drag to reposition nodes (double-click to unpin)
  • Zoom and pan
  • Impact chain highlighting on hover (broken nodes highlight dependents)
  • Dynamic arrow positioning (arrows connect to the closest box edge)
  • Source and status filtering via the legend

Version selection

The dashboard selects the current version of each OCI-backed service as the highest valid semver tag. Non-semver tags (e.g. latest, main) are excluded from version lists and never selected as the current version.

When you use “Fetch all versions” in the version history tab, all available versions are pulled from the OCI registry and cached locally (~/.cache/pacto/oci/). These cached versions survive dashboard restarts.

When a remote dependency is lazily resolved (via navigation to an unresolved dependency), the resolved bundle is also cached on disk. Its version history can be browsed and other versions can be loaded.

Diagnostics mode

Pass --diagnostics to enable debug endpoints (/api/debug/sources and /api/debug/services) that expose raw per-source data for troubleshooting.

pacto diff

Compares two contracts (local paths or oci:// references) and produces a classified change set (BREAKING, POTENTIAL_BREAKING, NON_BREAKING).

pacto diff <old> <new> [flags]

Examples:

  # Compare a remote contract with a local one
  pacto diff oci://ghcr.io/acme/svc-pacto:1.0.0 my-service

  # Markdown output for CI comments
  pacto diff --output-format markdown oci://ghcr.io/acme/svc-pacto:1.0.0 my-service

Flags:

  -h, --help                     help for diff
      --new-set stringArray      set a value on the new contract (e.g. --new-set service.version=2.0.0)
      --new-values stringArray   values file to merge into the new contract (can be repeated)
      --old-set stringArray      set a value on the old contract (e.g. --old-set service.version=1.0.0)
      --old-values stringArray   values file to merge into the old contract (can be repeated)

Exit code: Non-zero if breaking changes are detected.

The diff engine performs deep comparison of referenced OpenAPI specs, detecting changes at the path, method, parameter, request body, and response level. The optional docs/ directory is ignored entirely — documentation changes never produce diff entries or affect compatibility classification.

When both bundles include an sbom/ directory with recognized SBOM files (.spdx.json or .cdx.json), pacto diff reports package-level changes — added, removed, or modified packages (version and license). SBOM changes are informational and do not affect the overall classification or exit code.

When dependencies change between the old and new contracts (version upgrades, additions, or removals), a dependency graph diff section is displayed showing the tree of affected nodes.

See Change Classification for the full rules.

pacto doc

Reads a pacto.yaml in the given directory (or oci:// reference) and generates structured Markdown documentation.

pacto doc [dir | oci://ref] [flags]

Examples:

  # Print documentation to stdout
  pacto doc my-service

  # Write documentation to a file
  pacto doc my-service -o docs/

  # Serve documentation in the browser
  pacto doc my-service --serve

  # Serve on a custom port
  pacto doc my-service --serve --port 9090

  # Launch an interactive API explorer (Scalar UI)
  pacto doc my-service --ui swagger

  # Select a specific interface
  pacto doc my-service --ui swagger --interface public-api

  # Point try-it-out requests to a running backend
  pacto doc my-service --ui swagger --target http://localhost:3000

  # Per-interface target mapping
  pacto doc my-service --ui swagger --target public-api=http://localhost:3000 --target admin-api=http://localhost:3001

Flags:

  -h, --help                 help for doc
      --interface string     interface name to display (used with --ui)
  -o, --output string        output directory for generated Markdown file
      --port int             port for the documentation server (used with --serve or --ui) (default 8484)
      --serve                start a local HTTP server to view documentation in the browser
      --set stringArray      set a contract value (e.g. --set service.version=2.0.0)
      --target stringArray   target server URL for try-it-out requests; supports interface=url mapping (used with --ui)
      --ui string            UI type for interactive API explorer (e.g. swagger)
  -f, --values stringArray   values file to merge into the contract (can be repeated; last wins)

--serve, --ui, and --output are mutually exclusive.

Use --interface to select a specific OpenAPI interface when multiple are present. Without it, an index page is shown.

The --target flag supports per-interface mapping: --target api=http://localhost:3000 --target admin=http://localhost:4000.

Sibling dependencies are resolved in parallel. OCI bundles are cached locally in ~/.cache/pacto/oci/ for faster subsequent operations. Use --no-cache to bypass the cache.

pacto explain

Parses a pacto.yaml in the given directory (or oci:// reference) and produces a human-readable summary of the service contract.

pacto explain [dir | oci://ref] [flags]

Examples:

  pacto explain my-service

Flags:

  -h, --help                 help for explain
      --set stringArray      set a contract value (e.g. --set service.version=2.0.0)
  -f, --values stringArray   values file to merge into the contract (can be repeated; last wins)

pacto generate

Invokes a pacto-plugin- binary to generate deployment manifests, documentation, or other artifacts from a contract directory or oci:// reference.

pacto generate <plugin> [dir | oci://ref] [flags]

Examples:

  pacto generate helm my-service -o manifests/

Flags:

  -h, --help                 help for generate
      --option stringArray   plugin option as key=value (can be repeated)
  -o, --output string        output directory (default: <plugin>-output/)
      --set stringArray      set a contract value (e.g. --set service.version=2.0.0)
  -f, --values stringArray   values file to merge into the contract (can be repeated; last wins)

pacto graph

Resolves the dependency tree from a pacto.yaml in the given directory (or oci:// reference) and displays the graph, cycles, and version conflicts.

pacto graph [dir | oci://ref] [flags]

Examples:

  pacto graph my-service
  pacto graph --with-references
  pacto graph --only-references

Flags:

  -h, --help                 help for graph
      --only-references      Show only config/policy reference edges (no dependencies)
      --set stringArray      set a contract value (e.g. --set service.version=2.0.0)
  -f, --values stringArray   values file to merge into the contract (can be repeated; last wins)
      --with-references      Include config/policy reference edges alongside dependencies

Dependencies resolved from local paths are annotated with [local]. Shared dependencies (referenced by multiple parents) are annotated with (shared).

Reports cycles, version conflicts, and unreachable dependencies.

Sibling dependencies are resolved in parallel. OCI bundles are cached locally in ~/.cache/pacto/oci/ for faster subsequent operations. Use --no-cache to bypass the cache.

pacto init

Creates a new directory with pacto.yaml and the bundle directory structure (interfaces/, configuration/).

pacto init <name> [flags]

Examples:

  pacto init my-service

Flags:

  -h, --help   help for init

Scaffolds a bundle with a valid pacto.yaml, a placeholder OpenAPI spec, and a configuration JSON Schema. Only pacto.yaml is required — the interfaces/ and configuration/ directories are optional conveniences.

pacto login

Stores credentials for an OCI registry in ~/.config/pacto/config.json.

pacto login <registry> [flags]

Examples:

  pacto login ghcr.io -u my-username

Flags:

  -h, --help              help for login
  -p, --password string   registry password
  -u, --username string   registry username

Credentials are stored in ~/.config/pacto/config.json (or $XDG_CONFIG_HOME/pacto/config.json), keeping them separate from Docker’s configuration.

GitHub Container Registry (ghcr.io)

For GitHub registries (ghcr.io and docker.pkg.github.com), pacto can automatically reuse credentials from the GitHub CLI — no pacto login required.

If you already have gh installed and authenticated, pacto will use gh auth token to obtain a token transparently. To verify your setup:

# Check if gh is authenticated
gh auth status

# Verify the token is available
gh auth token

To push container images or packages, your token needs the write:packages scope. If you authenticated gh without it, refresh your scopes:

gh auth refresh --scopes write:packages

After this, pacto push oci://ghcr.io/... will work without any additional login step.

If gh is not installed or not authenticated, pacto silently falls back to the next credential source in the chain.

pacto mcp

Starts a Model Context Protocol (MCP) server exposing Pacto tools for AI agents. Supports stdio (default) and HTTP transports.

pacto mcp [flags]

Examples:

  # Start MCP server over stdio (default)
  pacto mcp

  # Start MCP server over HTTP
  pacto mcp -t http

  # Start MCP server on a custom port
  pacto mcp -t http --port 9090

Flags:

  -h, --help               help for mcp
      --port int           port for HTTP transport (default 8585)
  -t, --transport string   transport type: stdio or http (default "stdio")

The server exposes the following tools:

Tool Description
pacto_validate Validate a contract and return errors/warnings
pacto_inspect Return the full structured contract representation
pacto_resolve_dependencies Resolve the dependency graph, detecting cycles and conflicts
pacto_list_interfaces List interfaces exposed by a service
pacto_generate_docs Generate Markdown documentation from a contract
pacto_explain Return a human-readable summary of a contract
pacto_generate_contract Generate a new contract YAML from structured inputs
pacto_suggest_dependencies Suggest likely dependencies based on service characteristics
pacto_schema Return the Pacto JSON Schema and documentation link

All tools accept both local directory paths and oci:// references.

See MCP Integration for detailed setup instructions with Claude and other AI tools.

pacto pack

Validates the contract in the given directory and creates a tar.gz archive of the bundle, ready for distribution.

pacto pack [dir] [flags]

Examples:

  pacto pack my-service

Flags:

  -h, --help                 help for pack
  -o, --output string        output file path (default: <name>-<version>.tar.gz)
      --set stringArray      set a contract value (e.g. --set service.version=2.0.0)
  -f, --values stringArray   values file to merge into the contract (can be repeated; last wins)

The contract is validated before packing. If validation fails, no archive is created.

pacto pull

Pulls a contract bundle from the specified OCI reference and extracts it to a local directory.

pacto pull <ref> [flags]

Examples:

  # Pull a specific version
  pacto pull oci://ghcr.io/acme/my-service-pacto:1.0.0

  # Pull the latest available version
  pacto pull oci://ghcr.io/acme/my-service-pacto

Flags:

  -h, --help            help for pull
  -o, --output string   output directory (default: service name)

pacto push

Validates the contract, builds an OCI image, and pushes it to the specified registry reference.

pacto push <ref> [flags]

Examples:

  # Push with auto-tag (uses contract version)
  pacto push oci://ghcr.io/acme/my-service-pacto -p my-service

  # Push with explicit tag
  pacto push oci://ghcr.io/acme/my-service-pacto:latest -p my-service

  # Force overwrite an existing artifact
  pacto push oci://ghcr.io/acme/my-service-pacto -p my-service --force

Flags:

  -f, --force                overwrite existing artifact in registry
  -h, --help                 help for push
  -p, --path string          path to contract directory (default: current directory)
      --set stringArray      set a contract value (e.g. --set service.version=2.0.0)
      --values stringArray   values file to merge into the contract (can be repeated; last wins)

If the artifact already exists in the registry, pacto push prints a warning and exits successfully without pushing. Use --force to overwrite.

pacto update

Downloads and installs the specified version of pacto. If no version is given, updates to the latest release.

pacto update [version] [flags]

Examples:

  # Update to the latest release
  pacto update

  # Update to a specific version
  pacto update v1.1.0

Flags:

  -h, --help   help for update

pacto update is not available on dev builds. If you built from source without version injection, install a release build first.

Update notifications

When a newer version is available, pacto displays a notification after any command:

A new version of pacto is available: v1.0.0 -> v1.2.0
Run 'pacto update' to update.

The check runs asynchronously and adds no latency. Results are cached for 24 hours in ~/.config/pacto/update-check.json.

Notifications are suppressed when:

  • Running a dev build
  • Using --output-format json
  • The PACTO_NO_UPDATE_CHECK=1 environment variable is set

pacto validate

Validates a pacto.yaml in the given directory (or oci:// reference) against the specification, checking structural, cross-field, and semantic rules.

pacto validate [dir | oci://ref] [flags]

Examples:

  # Validate a local contract
  pacto validate my-service

  # Validate from current directory
  pacto validate

  # Validate from an OCI registry
  pacto validate oci://ghcr.io/acme/my-service-pacto:1.0.0

  # JSON output
  pacto validate --output-format json my-service

Flags:

  -h, --help                 help for validate
      --set stringArray      set a contract value (e.g. --set service.version=2.0.0)
  -f, --values stringArray   values file to merge into the contract (can be repeated; last wins)

Exit code: Non-zero if validation fails.

pacto version

Prints the current pacto version.

pacto version [flags]

Examples:

  pacto version

Flags:

  -h, --help   help for version

Environment variables

Variable Description
PACTO_CACHE_DIR Override the OCI bundle cache directory (default: ~/.cache/pacto/oci)
PACTO_NO_CACHE Set to 1 to disable OCI bundle caching (equivalent to --no-cache)
PACTO_NO_UPDATE_CHECK Set to 1 to disable automatic update checks
PACTO_REGISTRY_USERNAME Registry username for authentication
PACTO_REGISTRY_PASSWORD Registry password for authentication
PACTO_REGISTRY_TOKEN Registry token for authentication

Authentication

Pacto follows this credential resolution chain:

  1. Explicit CLI flags (--username, --password)
  2. Environment variables (PACTO_REGISTRY_USERNAME, PACTO_REGISTRY_PASSWORD, PACTO_REGISTRY_TOKEN)
  3. Pacto config (~/.config/pacto/config.json, written by pacto login)
  4. GitHub CLI (gh auth token, for ghcr.io and docker.pkg.github.com only)
  5. Docker config (~/.docker/config.json) and credential helpers
  6. Cloud auto-detection (ECR, GCR, ACR)
  7. Anonymous fallback

For GitHub registries, step 4 means you can skip pacto login entirely if you have gh authenticated with the write:packages scope (see pacto login above).

No credentials are ever stored in contract files.