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.

​
Install

npm install -g @vela-event/cli
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

1

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

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_...
3

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

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.

​
Next steps

Configuration

All config file options and CLI flags.

Schema Format

How to write schema JSON files.