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.

​
Config file

Create vela.config.json in your project root. The CLI looks for this file in the current directory when any command is run. 
{
  "app": "order-service",
  "schemasDir": "./vela/schemas"
}
FieldRequiredDefaultDescription
appyes—App slug or UUID. Find it in the dashboard or from vela.config.json after vela pull.
schemasDirno./vela/schemasPath to the directory containing your schema JSON files. Relative to the config file.
baseUrlnohttps://api.velahq.xyzOverride the API base URL. Useful for self-hosted instances.
Do not put clientSecret in vela.config.json. If you commit this file (you should), the secret would be exposed in your repository. Use the environment variable instead.

​
Authentication

Set the VELA_CLIENT_SECRET environment variable. It takes precedence over any other configuration. 
export VELA_CLIENT_SECRET="vela_cs_..."
For local development, load it from a .env file using a tool like dotenv-cli: 
dotenv -- vela push
For CI/CD, inject it as a secret: 
# GitHub Actions
- name: Push schemas
  run: npx @vela-event/cli push
  env:
    VELA_CLIENT_SECRET: ${{ secrets.VELA_CLIENT_SECRET }}

​
CLI flags

Every command accepts flags that override the config file. This is useful when managing multiple apps or environments from the same repository.
FlagDescription
--app <slug>Override the app slug or UUID
--dir <path>Override the schemas directory path
# Push to staging
vela push --app order-service-staging --dir ./schemas

# Push to production
vela push --app order-service-prod --dir ./schemas

​
Precedence

Settings are resolved in this order — highest wins:
  1. CLI flags (--app, --dir)
  2. Environment variables (VELA_CLIENT_SECRET)
  3. vela.config.json file
  4. Defaults (schemasDir: ./vela/schemas)

​
Self-hosted configuration

If you’re running Vela on your own infrastructure, override the base URL: 
{
  "app": "order-service",
  "baseUrl": "https://vela.your-domain.com"
}
Or use an environment variable: 
VELA_BASE_URL=https://vela.your-domain.com vela push

​
Multi-environment setup

For projects with separate staging and production apps, use a single schemas directory with environment-specific config files or flags: 
vela/
  schemas/           ← same schemas for all envs
    order.placed.json
    payment.failed.json
  config.staging.json
  config.prod.json

// config.staging.json
{
  "app": "order-service-staging",
  "schemasDir": "./vela/schemas"
}

# Push to staging
vela push --config vela/config.staging.json

# Push to production
vela push --config vela/config.prod.json