> ## 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 push

> Sync local schema files to the remote Vela API — creates new schemas and updates changed ones.

`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

```bash theme={null}
vela push
```

## 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

1. Reads all `.json` files from your schemas directory
2. Fetches all existing schemas from the Vela API for your app
3. Compares local vs. remote by `eventName`
4. **Creates** schemas that don't exist remotely yet
5. **Updates** schemas where fields, description, or metadata have changed
6. **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           |

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

The exit code is `1` if any schema failed.

## CI/CD deployment

Push schemas as part of your deployment pipeline, after your app code is deployed:

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

<Tip>
  Run `vela diff` before `vela push` in CI to get a clear audit trail of what changed in each deployment.
</Tip>

## 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.