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

> Manage event schemas as code — define them in JSON files, preview changes, and push to Vela. Like Prisma migrations, but for your event types.

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

<Steps>
  <Step title="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
    ```
  </Step>

  <Step title="Preview changes with vela diff">
    Before pushing anything, see exactly what would change — new schemas, updated fields, removed fields — without touching the remote API.

    ```bash theme={null}
    vela diff
    # ! order.placed → update
    #   + field "currency" (enum, required)
    # ! order.cancelled → create
    # ✓ payment.failed → no change
    ```
  </Step>

  <Step title="Push to sync">
    `vela push` creates or updates schemas that have changed. Unchanged schemas are skipped.

    ```bash theme={null}
    vela push
    # ✓ Created order.cancelled
    # ✓ Updated order.placed
    # i Created 1, Updated 1, Unchanged 1
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    vela pull
    # ✓ Pulled order.placed
    # ✓ Pulled payment.failed
    ```
  </Step>
</Steps>

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

```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 }}
```

And push on deploy:

```yaml theme={null}
- name: Push schemas
  run: npx @vela-event/cli push
  env:
    VELA_CLIENT_SECRET: ${{ secrets.VELA_CLIENT_SECRET }}
```

## Quick links

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install the CLI globally or use it with npx.
  </Card>

  <Card title="Schema Format" icon="file-code" href="/cli/schema-format">
    JSON schema file structure and field types.
  </Card>

  <Card title="vela diff" icon="code-compare" href="/cli/diff">
    Preview changes before pushing.
  </Card>

  <Card title="vela push" icon="arrow-up" href="/cli/push">
    Sync local schemas to remote.
  </Card>
</CardGroup>