Installation

Install

npm install -g @vela-event/cli

pnpm add -g @vela-event/cli

npx @vela-event/cli <command>

Installing globally lets you run vela directly. Using npx is better for CI environments where you want a specific version pinned in package.json.

Requirements

Node.js 18+
A Vela account with at least one app created
A client secret (vela_cs_...) — found in Settings → Client Secrets

Setup

Create a config file

In your project root, create vela.config.json:

{
  "app": "your-app-slug",
  "schemasDir": "./vela/schemas"
}

The app value is your app’s slug (e.g. order-service). You can find it in the dashboard or by running vela apps list once authenticated.

Set your client secret

Export the environment variable. Never put the secret in vela.config.json.

export VELA_CLIENT_SECRET="vela_cs_..."

For local dev, add it to your .env file (make sure .env is in .gitignore):

# .env
VELA_CLIENT_SECRET=vela_cs_...

Create the schemas directory

mkdir -p vela/schemas

This is where your schema JSON files will live. Add this directory to git so schemas are tracked alongside your code.

Verify

vela --help

Expected output:

Usage: vela <command> [options]

Commands:
  push    Sync local schema files to the remote Vela API
  pull    Download remote schemas to local JSON files
  diff    Show pending changes without pushing

Options:
  --app <slug>    App slug or ID (overrides vela.config.json)
  --dir <path>    Schemas directory (overrides vela.config.json)
  --help          Show this help message
  --version       Show version

Pinning a version in CI

For reproducible CI builds, pin the version in package.json instead of using latest:

{
  "devDependencies": {
    "@vela-event/cli": "^0.1.0"
  }
}

Then use npx @vela-event/cli push in your workflow, which resolves from node_modules without a separate global install step.

Overview

Commands

Reference

Installation

Install

Requirements

Setup

Pinning a version in CI

Next steps

Configuration

Schema Format

​Install

​Requirements

​Setup

​Pinning a version in CI

​Next steps

Configuration

Schema Format

Install

Requirements

Setup

Pinning a version in CI

Next steps