CLI & Script Checks (exec)

The exec step runs a shell command directly on the CI runner.

Use it to verify:

• Required tooling is installed
• Repository scripts succeed
• Environment assumptions hold
• Custom validation logic passes

exec checks enforce operational guarantees alongside API and database contracts.

Basic Example

version: 1
feature: demo
 
contracts:
  - name: environment
    checks:
      - id: node_present
        work_item: "KAN-124"
        says: "The CI runner must have Node installed"
        steps:
          - exec:
              run: "node -v"
            expect:
              exit_code: 0
              stdout_contains: "v"

Available Options

- exec:
    run: "npm run lint"
    cwd: "./web"
    env:
      NODE_ENV: test
    timeout_ms: 15000
    retries: 0
    max_output_chars: 8192

run

The command to execute (required).

cwd

Optional working directory for the command.

env

Optional environment variables scoped to this step.

Supported Expectations

expect:
  exit_code: 0
  stdout_contains: "v22"
  stderr_empty: true

Available assertions:

• exit_code
• stdout_contains / stderr_contains
• stdout_regex / stderr_regex
• stdout_not_contains / stderr_not_contains
• stdout_empty / stderr_empty
• max_duration_ms

Best Practices

• Keep checks deterministic.
• Avoid time-based or flaky scripts.
• Avoid external dependencies unless necessary.
• Use exec for invariants — not full test suites.

Treat each exec step as a system guarantee.