vela push reads your local schema files, compares them against the remote API, and creates or updates schemas that have changed. Unchanged schemas are skipped.
Usage
Example output
i Found 3 local schema(s) in ./vela/schemas
✓ Created order.cancelled
+ field "reason" (enum, required)
+ field "refundCents" (number, optional)
✓ Updated order.placed
~ description changed
+ field "currency" (enum, required)
order.shipped → no change (skipped)
i Done: 1 created, 1 updated, 1 unchanged
What happens step by step
- Reads all
.json files from your schemas directory
- Fetches all existing schemas from the Vela API for your app
- Compares local vs. remote by
eventName
- Creates schemas that don’t exist remotely yet
- Updates schemas where fields, description, or metadata have changed
- Skips schemas that are identical to remote — no API call is made
Options
| Flag | Description |
|---|
--app <slug> | Override the app slug from vela.config.json |
--dir <path> | Override the schemas directory path |
# Push to a staging app
vela push --app order-service-staging
# Push schemas from a different directory
vela push --dir ./schemas/v2
Error handling
If a schema fails to create or update, the error is shown inline and the CLI continues with the remaining schemas:
✗ Failed order.placed
Validation error: field "orderId" has type mismatch (expected string, got number)
✓ Created payment.failed
i Done: 1 created, 0 updated, 0 unchanged, 1 failed
1 if any schema failed.
CI/CD deployment
Push schemas as part of your deployment pipeline, after your app code is deployed:
# .github/workflows/deploy.yml
jobs:
deploy:
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Install CLI
run: npm install -g @vela-event/cli
- name: Push schemas
run: vela push
env:
VELA_CLIENT_SECRET: ${{ secrets.VELA_CLIENT_SECRET }}
Run vela diff before vela push in CI to get a clear audit trail of what changed in each deployment.
Removing schemas
vela push does not delete remote schemas that have no local counterpart. Deletion must be done explicitly through the dashboard or the Management API. This is intentional — accidental file deletion should not automatically destroy production event schemas.
Dry run
To preview what vela push would do without making any changes, use vela diff instead.
