Skip to main content
vela diff compares your local schema files against the remote API and prints a summary of what would change. It makes no mutations.

​
Usage

vela diff

​
Example output

i Found 3 local schema(s) in ./vela/schemas

! order.cancelled  → create
  + field "reason" (enum, required)
    enumValues: card_error, fraud, customer_request
  + field "refundCents" (number, optional)

! order.placed  → update
  ~ description changed
  + field "currency" (enum, required)
    enumValues: USD, EUR, GBP

✓ payment.failed  → no change

i Summary: 1 to create, 1 to update, 1 unchanged

​
Legend

SymbolMeaning
!Schema has pending changes (will be created or updated)
✓Schema is identical to remote — no action needed
+Field will be added
-Field will be removed
~Field or description has changed

​
Exit codes

CodeMeaning
0All schemas are in sync — no changes pending
1Changes detected — one or more schemas would be created or updated
Exit code 1 does not mean an error occurred. It means drift was detected. Use this in CI to fail the build when schemas are out of sync.

​
CI usage

Use vela diff as a gate in your pipeline to catch schema drift before it reaches production: 
# Fail CI if schemas are out of sync
vela diff
echo "exit code: $?"
Or with a descriptive message: 
vela diff || { echo "Schema drift detected — run 'vela push' to sync"; exit 1; }

​
GitHub Actions example

# .github/workflows/ci.yml
- name: Check schema drift
  run: npx @vela-event/cli diff
  env:
    VELA_CLIENT_SECRET: ${{ secrets.VELA_CLIENT_SECRET }}
This job will fail if any schema is out of sync, blocking the PR from merging until schemas are pushed.

​
Options

FlagDescription
--app <slug>Override the app from vela.config.json
--dir <path>Override the schemas directory
# Diff against a specific app
vela diff --app order-service-staging

# Diff a different schemas directory
vela diff --dir ./schemas/v2

​
When schemas match

If all local schemas match the remote, vela diff prints: 
i Found 2 local schema(s) in ./vela/schemas
✓ order.placed   → no change
✓ payment.failed → no change

i All schemas are in sync.
And exits with code 0.

​
Difference from vela push

vela diff is a read-only preview. vela push actually applies the changes. Running vela diff before vela push is a good habit — see the plan, then execute it.