Skip to content

Contract overrides

Overrides change contract values at the command line without editing pacto.yaml, the same way Helm values work:

pacto validate . --set service.version=2.0.0 -f values-prod.yaml

Overrides are available on all commands that take a contract reference: validate, explain, doc, generate, graph, pack, push and lock. The two commands that take a pair of contracts (diff, impact) use the prefixed flags in Diff overrides. See the CLI reference for the complete command and flag listing.

Override flags

Flag Short Description
--values <file> -f Merge a YAML values file into the contract
--set <key=value> Set an individual value using dot-notation

Note

The -f shorthand is not available on pacto push because -f is already used for --force.

Precedence

Overrides follow the same precedence logic as Helm (lowest to highest):

  1. Base pacto.yaml
  2. Values files (-f), in the order they are specified
  3. --set values

Later sources override earlier ones. Multiple -f flags are applied in order — the last file wins for any conflicting key.

--set type inference

--set key=value infers the value's type from the string, trying in order: integer (int64) → float (float64) → boolean → string. The first parse that succeeds wins; anything that matches none stays a string. Consequences worth knowing:

  • --set readiness.minScore=80 → integer 80; --set ratio=1.5 → float 1.5.
  • --set flag=true → boolean true (but --set flag=1 → integer 1, not boolean).
  • A multi-dot semver like --set service.version=1.0.0 has two dots, so it parses as none of the numeric/boolean types and stays a string (the desired result). A two-segment value like 1.0 parses as the float 1.0 — quote-sensitive values that must remain strings are better set via a -f values file with explicit YAML typing.

Examples

# Override the service version
pacto validate my-service --set service.version=2.0.0

# Use a values file for environment-specific overrides
pacto validate my-service -f staging-values.yaml

# Combine both (--set takes precedence over -f)
pacto validate my-service -f staging-values.yaml --set service.version=3.0.0

# Set configuration values validated against the config schema
pacto validate my-service --set configurations[0].values.DB_HOST=localhost

# Set array elements using bracket notation
pacto validate my-service --set interfaces[0].visibility=internal

A worked per-environment layout — one values file per environment, the array-replacement caveat and this precedence rule applied end to end — is in Configurations as composable claims.

Diff overrides

diff and impact each take two contract references — an old one and a new one — so they carry no plain --values/--set. To override each side independently, use prefixed flags:

Flag Description
--old-values <file> Values file for the old (first) contract
--old-set <key=value> Set value for the old contract
--new-values <file> Values file for the new (second) contract
--new-set <key=value> Set value for the new contract 
# Override only the new contract
pacto diff oci://ghcr.io/acme/svc-pacto:1.0.0 my-service --new-set service.version=2.0.0

# Override both contracts
pacto diff old-service new-service \
  --old-values old-env.yaml \
  --new-values new-env.yaml \
  --new-set service.version=3.0.0

# The same four flags work on impact
pacto impact old-service new-service --new-set service.version=2.0.0

Schema validation

All overrides are validated against the Pacto JSON Schema after they are applied. This means invalid enum values, unknown fields and type mismatches are rejected by every command — not just validate and push.

# Rejected: "invalid" is not a valid enum value for state.type
pacto explain my-service --set state.type=invalid

# Rejected: "unknownField" is not defined in the schema
pacto doc my-service --set service.unknownField=value