CLI Reference¶

Most commands support --output-format json for programmatic consumption and --output-format markdown for rich markdown output (e.g. CI comments); the interactive and side-effecting commands (login, logout, update, mcp, dashboard) always emit text. Every command accepts -v / --verbose for debug-level logging and --help for detailed usage.

Global flags¶

      --config string          config file path
  -h, --help                   help for pacto
      --no-anim                disable animations
      --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.

Constraints apply to the CLI's dependency graph, not dashboard discovery

compatibility constraints are applied by the CLI when resolving a contract's declared dependencies (e.g. pacto graph). The dashboard's version discovery selects the highest semver tag and does not apply per-dependency compatibility constraints. Root-contract pulls (a tagless top-level oci:// ref) also select the highest semver tag with no constraint.

`pacto dashboard`¶

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

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.

Each positional argument is a pacto source reference: - oci://registry/repo → OCI registry source (can be repeated) - ./path/to/dir → local filesystem source (at most one)

When no arguments are given, sources are auto-detected: - 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: auto-discovered from K8s status.contract.resolvedRef, or via PACTO_DASHBOARD_REPO env var

Materialized bundles on disk (~/.cache/pacto/oci) are used internally by the OCI source to enrich version data (hash, classification, timestamps) without appearing as a separate source. The --no-cache flag skips pre-existing cache at startup but still allows same-session materialization (e.g. fetch-all-versions).

When running alongside the Kubernetes operator, OCI repositories are automatically discovered from the status.contract.resolvedRef fields of Pacto CRD resources. This provides full contract bundles, version history, interfaces, and diffs — without needing explicit OCI arguments. 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 (contract status, checks, endpoints) - OCI for contract content and version history - Local for in-progress contract changes

pacto dashboard [sources...] [flags]

Examples:

  # Start dashboard with auto-detected sources
  pacto dashboard

  # Start from a specific directory
  pacto dashboard ./services

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

  # Mix local and OCI sources
  pacto dashboard ./services oci://ghcr.io/org/payment-service

  # Custom port
  pacto dashboard --port 9090

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

Flags:

      --cors-origin string   explicit cross-origin allowed to call the API (default: same-origin only)
      --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)

It auto-detects sources: pass OCI repositories as arguments, or run it next to the operator (with a kubeconfig) and it discovers OCI repositories from each Pacto resource's status.contract.resolvedRef. Use --no-cache for a cold start (it skips scanning pre-existing cached bundles; bundles fetched during the session are still cached), and --diagnostics to expose the /api/debug/* endpoints.

For the source model, contract-first merge priority (local > oci > cache) and version-tracking design, see Architecture. For a tour of what the dashboard surfaces, see For platform engineers; to run it as a container, see Dashboard container.

`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; a NAME.html value writes a static documentation site to a NAME/ directory instead
      --port int             port for the documentation server (used with --serve or --ui) (default 8484)
      --serve                serve the offline dashboard-grade documentation site over a local HTTP server
      --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)

Markdown prints to stdout by default. -o DIR writes DIR/<service>.md. -o NAME.html writes a self-contained static documentation site (a directory) that reuses the dashboard UI offline.

--serve serves that static site locally. --ui swagger launches an interactive API explorer.

--serve, --ui and -o are mutually exclusive. Use --interface to pick one OpenAPI interface with --ui. --target and --target iface=url point try-it-out at a backend.

Sibling dependencies are resolved in parallel. OCI bundles cache under ~/.cache/pacto/oci/. --no-cache bypasses 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)

Readiness output. When the contract declares a readiness section (requires pactoVersion: "1.2"), explain adds a Readiness block: the derived Score, the Gate result (PASS/FAIL with score / minScore), Earned and Total Weight, the partial credit multiplier, the assessment expires date with countdown (or an Expired state), and a per-check table showing each check's declared status (done/partial/not-done/deferred), category, weight, earned weight, and evidence. The Readiness block also includes a revision-history table when history[] is present. --output-format json includes the same data plus doneCount, partialCount, notDoneCount, deferredCount, and expired (boolean). Readiness status is time-dependent — the score is 0 when the current date is past the assessment-level expires.

`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 generate <plugin> invokes the pacto-plugin-<plugin> binary. See Plugins for plugin discovery, the plugin registry, and the official plugins bundled with Pacto.

`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 lock`¶

Resolves the full transitive dependency and reference closure and writes a committed pacto.lock pinning each to its OCI digest. With --check, verifies the existing lock without writing.

pacto lock [dir] [flags]

Examples:

  pacto lock
  pacto lock --update
  pacto lock --update-name auth
  pacto lock --check

Flags:

      --check                     verify pacto.lock is up to date without writing (non-zero exit on drift)
  -h, --help                      help for lock
      --set stringArray           set a contract value (e.g. --set service.version=2.0.0)
      --update                    re-resolve dependencies to the newest version within their constraint
      --update-name stringArray   re-resolve only the named dependency, preserving all other pins (repeatable)
  -f, --values stringArray        values file to merge into the contract (can be repeated; last wins)

See Lockfile for the lock model, drift enforcement, and how .pactoignore keeps a pacto.lock out of a pushed bundle.

`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 logout`¶

Removes credentials for an OCI registry from ~/.config/pacto/config.json.

pacto logout <registry> [flags]

Examples:

  pacto logout ghcr.io

Flags:

  -h, --help   help for logout

`pacto mcp`¶

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

When a bundle reference (local directory or oci:// ref) is given, the server also exposes one executable tool per OpenAPI operation in the bundle's http interfaces, plus a pacto_skill tool for any skills/*.md domain knowledge. Read-only (GET/HEAD) operations are exposed by default; pass --allow-writes to expose mutating operations.

pacto mcp [bundle-ref] [flags]

Examples:

  # Start MCP server over stdio (default)
  pacto mcp

  # Start MCP server over HTTP
  pacto mcp -t http

  # Expose a bundle's OpenAPI operations as agent tools
  pacto mcp ./my-service --base-url https://api.example.com

  # Include mutating operations and an auth credential
  pacto mcp oci://ghcr.io/acme/svc:1.0.0 --base-url https://api.example.com \
    --auth bearerAuth=$TOKEN --allow-writes

Flags:

      --allow-writes       expose mutating operations (POST/PUT/PATCH/DELETE) as tools
      --auth stringArray   credential for a security scheme as name=value (repeatable)
      --base-url string    base URL for live invocation (overrides the OpenAPI servers[] URL)
  -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_create`	Create a new contract from intent-level inputs (name, description, interfaces, runtime semantics). Supports dry run.
`pacto_edit`	Edit an existing contract — add/remove interfaces and dependencies, change runtime, update metadata. Supports dry run.
`pacto_check`	Validate a contract and return errors, warnings, and actionable improvement suggestions.
`pacto_schema`	Return the Pacto format explanation and full JSON Schema reference.

These four authoring tools operate on local contract directories (they read and write pacto.yaml on disk) and do not resolve oci:// refs. When a bundle reference (a local directory or an oci:// ref) is passed on the command line, it is resolved and its OpenAPI operations are additionally exposed as executable agent tools, alongside a pacto_skill tool for any bundled skills.

See MCP Integration for detailed setup with Claude and other AI tools, and Agent capabilities for serving a bundle's operations as 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.

Files matched by .pactoignore are excluded from the archive — see Packaging ignore.

`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 (including remote policy and config refs), builds an OCI artifact, 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.

--values has no -f shorthand on push

On every other override-taking command -f is the shorthand for --values. On pacto push, -f is --force, so --values must be spelled out in full here.

`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

Note

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 or --output-format markdown (the notice shows only for text output) - 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

  # Also enforce the readiness gate (fail if score < minScore)
  pacto validate --readiness my-service

Flags:

  -h, --help                 help for validate
      --readiness            also enforce the readiness gate: fail if the derived readiness score is below the declared (or default 100) minScore. Opt-in because gate evaluation is time-dependent (check expiry is compared against the run time), which would otherwise make plain validation non-deterministic
      --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 --readiness gate is opt-in because it is time-dependent: it compares each check's expires against the run time, which would make plain validate non-deterministic. Without the flag, validation only checks the contract's structure and rules (readiness checks are still validated for shape, but the freshness gate is not enforced). See the readiness reference for the score and gate semantics.

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`	Cache directory for the `pacto dashboard` bundle scan. The core CLI cache location is controlled by `XDG_CACHE_HOME` (see below).
`PACTO_NO_CACHE`	Set to `1` to disable OCI bundle caching (equivalent to `--no-cache`)
`PACTO_NO_ANIM`	Set to `1` to disable spinners and animations (equivalent to `--no-anim`)
`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
`XDG_CONFIG_HOME`	Override config directory (default: `~/.config`). Affects `pacto login` credentials and update check cache
`XDG_CACHE_HOME`	Override cache directory (default: `~/.cache`). Affects OCI bundle cache location

Dashboard environment variables¶

The following variables configure the dashboard when set (see also Dashboard Container):

Variable	Description
`PACTO_DASHBOARD_REPO`	Comma-separated OCI repositories (fallback when no positional args)
`PACTO_DASHBOARD_HOST`	Bind address (default: `127.0.0.1`)
`PACTO_DASHBOARD_PORT`	HTTP port (default: `3000`)
`PACTO_DASHBOARD_NAMESPACE`	Kubernetes namespace filter (empty = all)
`PACTO_DASHBOARD_DIAGNOSTICS`	Enable debug endpoints

Authentication¶

Pacto follows this credential resolution chain:

Environment variables (PACTO_REGISTRY_TOKEN, or PACTO_REGISTRY_USERNAME + PACTO_REGISTRY_PASSWORD)
Pacto config (~/.config/pacto/config.json, written by pacto login — where --username / --password are persisted)
GitHub CLI (gh auth token, for ghcr.io and docker.pkg.github.com only)
Docker config (~/.docker/config.json) and credential helpers (including cloud-registry helpers for ECR, GCR and ACR)
Anonymous fallback

For GitHub registries, step 3 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.

CLI Reference¶

Global flags¶

OCI version resolution¶

pacto dashboard¶

pacto diff¶

pacto doc¶

pacto explain¶

pacto generate¶

pacto graph¶

pacto init¶

pacto lock¶

pacto login¶

GitHub Container Registry (ghcr.io)¶

pacto logout¶

pacto mcp¶

pacto pack¶

pacto pull¶

pacto push¶

pacto update¶

Update notifications¶

pacto validate¶

pacto version¶

Environment variables¶

Dashboard environment variables¶

Authentication¶

`pacto dashboard`¶

`pacto diff`¶

`pacto doc`¶

`pacto explain`¶

`pacto generate`¶

`pacto graph`¶

`pacto init`¶

`pacto lock`¶

`pacto login`¶

`pacto logout`¶

`pacto mcp`¶

`pacto pack`¶

`pacto pull`¶

`pacto push`¶

`pacto update`¶

`pacto validate`¶

`pacto version`¶