> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velahq.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vela diff

> Preview schema changes before pushing — see exactly what would be created or updated without touching the remote API.

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

## Usage

```bash theme={null}
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

| Symbol | Meaning                                                 |
| ------ | ------------------------------------------------------- |
| `!`    | 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

| Code | Meaning                                                            |
| ---- | ------------------------------------------------------------------ |
| `0`  | All schemas are in sync — no changes pending                       |
| `1`  | Changes 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:

```bash theme={null}
# Fail CI if schemas are out of sync
vela diff
echo "exit code: $?"
```

Or with a descriptive message:

```bash theme={null}
vela diff || { echo "Schema drift detected — run 'vela push' to sync"; exit 1; }
```

### GitHub Actions example

```yaml theme={null}
# .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

| Flag           | Description                              |
| -------------- | ---------------------------------------- |
| `--app <slug>` | Override the app from `vela.config.json` |
| `--dir <path>` | Override the schemas directory           |

```bash theme={null}
# 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.