Skip to main content

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.

​
Why schema-as-code?

Without the CLI, you register schemas by calling the API manually — once per environment, with no history. With the CLI, your schemas live as JSON files in your repository. They get reviewed in pull requests, deployed through CI/CD, and rolled back with git revert. Schema drift — where your code sends a field that no longer matches what Vela expects — becomes a build failure instead of a silent 400 at runtime.

​
How it works

1

Define schemas as JSON files

Create one .json file per event type in vela/schemas/. Each file describes the event name, required fields, and validation rules.
vela/schemas/
  order.placed.json
  order.cancelled.json
  payment.failed.json
2

Preview changes with vela diff

Before pushing anything, see exactly what would change — new schemas, updated fields, removed fields — without touching the remote API.
vela diff
# ! order.placed → update
#   + field "currency" (enum, required)
# ! order.cancelled → create
# ✓ payment.failed → no change
3

Push to sync

vela push creates or updates schemas that have changed. Unchanged schemas are skipped.
vela push
# ✓ Created order.cancelled
# ✓ Updated order.placed
# i Created 1, Updated 1, Unchanged 1
4

Pull to stay in sync

If schemas were modified in the dashboard or by another team member, vela pull downloads them as local files so your repo stays current.
vela pull
# ✓ Pulled order.placed
# ✓ Pulled payment.failed

​
CI/CD integration

Add vela diff as a check in your CI pipeline. It exits with code 1 when schemas are out of sync, failing the build before drift reaches production. 
# .github/workflows/ci.yml
- name: Check schema drift
  run: npx @vela-event/cli diff
  env:
    VELA_CLIENT_SECRET: ${{ secrets.VELA_CLIENT_SECRET }}
And push on deploy: 
- name: Push schemas
  run: npx @vela-event/cli push
  env:
    VELA_CLIENT_SECRET: ${{ secrets.VELA_CLIENT_SECRET }}

Installation

Install the CLI globally or use it with npx.

Schema Format

JSON schema file structure and field types.

vela diff

Preview changes before pushing.

vela push

Sync local schemas to remote.