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 an operational 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, organised around four workflows: an operational Overview, the Services inventory, the Operational Graph, and Change analysis.
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
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)
--trace-source stringArray named offline OTLP/JSON trace source as NAME=PATH, where NAME is its stable data-source identity (repeatable; also PACTO_DASHBOARD_TRACE_SOURCES)
--traces stringArray OTLP/JSON trace file to fold observed dependencies from (repeatable; also PACTO_DASHBOARD_TRACES)
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).
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.
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 evidence¶
Produce and verify the signed, versioned envelopes that carry a Pacto EvidenceSet from a remote or disconnected environment to a platform that ingests it. Keys are Ed25519; the wire format is defined by pkg/evidenceenvelope.
Flags:
pacto explain¶
Parses a pacto.yaml in the given directory (or oci:// reference) and produces a human-readable summary of the service contract.
Examples:
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 (a pactoVersion: "2.0" feature), 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 fleet¶
Compose contracts, contract revisions and operational targets from local bundles and ingested evidence into a versioned, navigable graph, then search, inspect, traverse and explain it. Every answer reports its as-of time and completeness.
Flags:
--cache include every bundle in the local OCI cache as an offline baseline revision
--evidence-url stringArray base URL of an Evidence Server to consume its read-only operational-graph contribution over HTTP (repeatable)
--freshness duration mark target evidence older than this as stale (0 disables)
-h, --help help for fleet
--k8s include live Pacto CRs from the current Kubernetes cluster as targets
--local stringArray local bundle root(s) to scan (repeatable) (default [.])
--namespace string namespace to read Pacto CRs from with --k8s (empty = all namespaces)
--oci stringArray registry reference to include as a published-baseline revision (repeatable)
--target-state stringArray offline target-state fixture file(s) supplying targets — a demo/test adapter, not the signed EvidenceSet protocol (repeatable)
--traces stringArray OTLP/JSON trace file supplying runtime-observed dependency edges, folded into the snapshot as observed relationships (repeatable)
pacto generate¶
Invokes a pacto-plugin-
Examples:
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.
Examples:
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 impact¶
Composes a semantic contract diff (old→new) with the operational graph to answer what a change's real blast radius is: which consumers are affected, how strong the evidence is and whether their declared compatibility still holds.
Exit status is non-zero when the change is BREAKING and at least one active consumer is incompatible with the new version (mirrors pacto diff).
Examples:
# Impact of upgrading a local service against the local fleet
pacto impact ./svc-v1 ./svc-v2 --local .
# Include observed (runtime) evidence and emit JSON
pacto impact oci://ghcr.io/acme/svc:1.0.0 ./svc --include-observed --output-format json
Flags:
--freshness duration mark target evidence older than this as stale (0 disables)
-h, --help help for impact
--include-observed let observed (runtime) relationships raise consumer confidence
--local stringArray local bundle root(s) to scan (repeatable) (default [.])
--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)
--target-state stringArray offline target-state fixture file(s) supplying targets (repeatable)
--traces string OTLP/JSON trace file; its observed edges corroborate and surface consumers (implies --include-observed)
pacto init¶
Creates a new directory with pacto.yaml and the bundle directory structure (interfaces/, configuration/).
Examples:
Flags:
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.
Examples:
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.
Examples:
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:
To push container images or packages, your token needs the write:packages scope. If you authenticated gh without it, refresh your scopes:
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.
Examples:
Flags:
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.
With --root, the server instead exposes a read-only contract catalog: the given roots plus their dependency closure, resolved once at startup and then frozen, so a registry tag that moves later does not change the session. Roots that do not resolve stay visible as partial knowledge. Discovery is not authorization and nothing in the catalog executes.
A bundle reference, --root and --fleet select different servers and cannot be combined.
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
# Expose a contract catalog discovered from explicit roots
pacto mcp --root oci://ghcr.io/acme/platform:1.4.0 --root ./experimental-platform
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)
--cache include the local OCI cache as offline baseline revisions (--fleet)
--evidence-url stringArray base URL of an Evidence Server to consume over HTTP for --fleet (repeatable)
--fleet expose read-only operational-graph (fleet) query tools
--freshness duration mark target evidence older than this as stale (--fleet)
-h, --help help for mcp
--k8s include live Pacto CRs from the current Kubernetes cluster (--fleet)
--local stringArray local bundle root(s) for --fleet (repeatable) (default [.])
--namespace string namespace for --k8s (empty = all namespaces)
--oci stringArray registry reference to include as a published-baseline revision for --fleet (repeatable)
--port int port for HTTP transport (default 8585)
--root stringArray contract root to discover a read-only catalog from: a local bundle path or an oci:// reference (repeatable)
--target-state stringArray offline target-state fixture file(s) for --fleet — a demo/test adapter (repeatable)
-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.
Server modes¶
The default server exposes the authoring tools above. Three flags select a different server instead, and they cannot be combined — passing more than one is an error, never a silent choice:
| Invocation | Server |
|---|---|
pacto mcp |
Authoring tools. |
pacto mcp <bundle-ref> |
Authoring tools plus the bundle's OpenAPI operations as executable agent tools, alongside a pacto_skill tool for any bundled skills. |
pacto mcp --fleet |
Authoring tools plus read-only operational-graph query tools. |
pacto mcp --root <ref> [--root <ref>] |
A read-only contract catalog discovered from the named roots, and nothing else: catalog mode registers no authoring tools, so nothing reachable in it writes to disk. |
--root is repeatable and takes a local bundle directory or an oci:// reference. The roots and their dependency closure are resolved once, at startup, through the same reference parsing, credentials and cache the rest of the CLI uses; after that the session is frozen, so a tag that moves in a registry does not change any answer. Roots that do not resolve stay visible with a classified reason and the catalog reports itself as partial. Nothing is crawled, nothing is refreshed and nothing is persisted.
See MCP Integration for detailed setup with Claude and other AI tools, Agent capabilities for serving a bundle's operations as tools, and Contract catalog discovery for the catalog surface.
pacto otel¶
Flags:
pacto pack¶
Validates the contract in the given directory and creates a tar.gz archive of the bundle, ready for distribution.
Examples:
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.
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:
pacto push¶
Validates the contract (including remote policy and config refs), builds an OCI artifact, and pushes it to the specified registry reference.
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.
Examples:
Flags:
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:
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.
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.
Examples:
Flags:
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, orPACTO_REGISTRY_USERNAME+PACTO_REGISTRY_PASSWORD) - Pacto config (
~/.config/pacto/config.json, written bypacto login— where--username/--passwordare persisted) - GitHub CLI (
gh auth token, forghcr.ioanddocker.pkg.github.comonly) - 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.