CLI Commands

All commands read from contractual.yaml in the current directory.

Global options

All commands support these flags:

Flag	Alias	Description
`--help`	`-h`	Show help for command
`--version`		Show CLI version
`--yes`	`-y`	Skip interactive prompts, use defaults
`--interactive`		Force interactive mode (even in CI)
`--json`		Output as JSON (implies `--yes`)
`--quiet`	`-q`	Minimal output
`--verbose`	`-v`	Detailed output
`--config`	`-c`	Path to contractual.yaml (default: auto-detect)

init

Scan the project for spec files and generate the initial configuration.

contractual init [options]

Option	Alias	Description	Default
`--dir <path>`		Root directory to scan	`.`
`--initial-version`	`-V`	Initial version for contracts	`0.0.0`
`--versioning`		Versioning mode: `independent` or `fixed`	`independent`
`--force`	`-f`	Reinitialize even if config exists	`false`
`--format <fmt>`		Output format: `text` or `json`	`text`

What it does:

Scans for OpenAPI and JSON Schema files
Creates contractual.yaml with detected contracts
Creates .contractual/ directory with initial snapshots

terminal

$ contractual init

Scanning for contract specs...

Detected specs
✔  openapi      api/openapi.yaml
✔  json-schema  schemas/user.schema.json

Created contractual.yaml
Created .contractual/
Wrote snapshots for 2 contract(s)

lint

Validate specs against their format specification.

contractual lint [contracts...] [options]

Option	Description	Default
`--contract <name>`	Lint only named contract(s)	All
`--fix`	Auto-fix issues where possible	Off
`--format <fmt>`	Output format: `text`, `json`, or `stylish`	`text`

terminal

$ contractual lint

Linting contracts...

payments-api  (openapi)
✖  [error]  oas3-api-servers  No servers defined  api/openapi.yaml:1
✔  user-schema  (json-schema)  No violations

1 contract(s) passed, 1 contract(s) have errors.

diff

Show all changes between current specs and their last versioned snapshots, classified by severity.

contractual diff [contracts...] [options]

Option	Alias	Description	Default
`--contract <name>`		Diff only named contract(s)	All
`--base`	`-b`	Compare against specific version	Latest
`--format <fmt>`		Output format: `text`, `json`, or `markdown`	`text`
`--severity <level>`		Filter: `all`, `breaking`, `non-breaking`, `patch`	`all`
`--verbose`		Show JSON Pointer paths for each change	Off

Unlike breaking, which exits 1 if breaking changes exist, diff is informational—it always exits 0 and shows every change.

terminal

$ contractual diff

orders-api: 3 changes (2 breaking, 1 non-breaking) — suggested bump: major

BREAKING     Removed endpoint GET /orders/{id}/details
BREAKING     Changed type of field 'amount': string → number
non-breaking  Added optional field 'tracking_url'

order-schema: no changes

breaking

Compare specs against snapshots and exit 1 if breaking changes are found. This is the CI gate command.

contractual breaking [--contract <name>] [--format <fmt>] [--base <ref>]

Option	Description	Default
`--contract <name>`	Check only named contract(s)	All
`--format <fmt>`	Output format: `text` or `json`	`text`
`--base <ref>`	Snapshot tag or git ref to compare against	Latest

terminal

$ contractual breaking

Comparing contracts against last snapshot...

payments-api  (openapi)
✖  [breaking]      DELETE /v1/charges/{id}  Endpoint removed
✔  [non-breaking]  GET /v1/charges          Response field `metadata` added

user-schema  (json-schema)
✔  No changes detected.

1 breaking change(s) found.

changeset

Create a changeset file for detected changes.

contractual changeset [options]

Option	Description	Default
`--no-interactive`	Auto-generate without prompts	Off
`--empty`	Create changeset with no spec changes	Off
`--message`	Changeset summary (skip prompt)	Interactive

terminal

$ contractual changeset

Detected changes in payments-api (openapi):
✖  [breaking]      DELETE /v1/charges/{id}  Endpoint removed

? Bump type for payments-api: (major)
? Summary: Remove deprecated endpoint

Wrote .contractual/changesets/fuzzy-lion-dances.md

version

Consume changesets and bump versions.

contractual version [options]

Option	Description	Default
`--dry-run`	Preview without writing files	Off
`--no-changelog`	Skip CHANGELOG.md update	Off
`--no-git`	Skip git operations	Off
`--preid`	Pre-release identifier override	From pre.json

terminal

$ contractual version

Reading changesets...
fuzzy-lion-dances.md   →  payments-api  major

Resolved bump types:
payments-api   1.4.2  →  2.0.0  (major)

Snapshotting specs...
✔  .contractual/snapshots/payments-api@2.0.0.yaml

Updated .contractual/versions.json
Updated CHANGELOG.md
Deleted 1 changeset file(s)

Done. Commit these changes to complete the release.

status

Show current versions and pending changesets.

contractual status [options]

Option	Description	Default
`--format <fmt>`	Output format: `text` or `json`	`text`
`--pending`	Show only contracts with pending changes	Off

terminal

$ contractual status

Contract Versions
─────────────────────────────────────────────────────
payments-api   v1.4.2  →  v2.0.0  (major pending)
user-schema    v0.9.1  ✔  up to date

Pending changesets (1):
fuzzy-lion-dances.md
  contracts: payments-api  bump: major

Run `contractual version` to apply these changesets.

contract

Manage contracts in the project. See Contract Management for full documentation.

contractual contract add      # Add a new contract
contractual contract list     # List all contracts
contractual contract remove   # Remove a contract

pre

Manage pre-release versions. See Pre-release Versioning for full documentation.

contractual pre enter <tag>   # Enter pre-release mode (alpha, beta, rc)
contractual pre exit          # Exit pre-release mode
contractual pre status        # Show pre-release state

Exit codes

Code	Meaning	Commands
`0`	Success	All
`1`	Breaking changes or lint errors found	`lint`, `breaking`, `status`
`2`	Configuration error	All
`3`	Tool execution error	`lint`, `breaking`
`4`	User cancelled operation	Interactive commands

See Exit Codes for detailed explanations.