Configuration

ev.yaml

ev.yaml is created by ev init at the root of your git repository and should be checked into version control. It defines the project boundary and provides default context so you don't have to pass flags on every command.

Minimal Config

project: clxxxxxxxxxxxxxxxxxxxxxxxx
name: my-project
default_env: dev
env_files:
  - .env
  - .env.local

That is all you need for a single-app project. ev treats the repo root as the one app.

All Fields

Monorepo Config

project: clxxxxxxxxxxxxxxxxxxxxxxxx
name: my-project
default_env: dev
env_files:
  - .env
  - .env.local
 
apps:
  frontend:
    path: packages/frontend
  backend:
    path: packages/backend
  worker:
    path: packages/worker

The key name (e.g., frontend, backend) is the app's display name used in all ev commands and the dashboard. Renaming a key in ev.yaml does not rename the app on the server — the next ev push creates a new app with the new name. Delete the old app by name with ev delete <old-name>.

When you run ev commands from packages/backend/, ev automatically resolves the app to backend. You can override with colon syntax:

ev push                    # auto-detected from cwd
ev push backend:staging    # explicit app and environment
ev pull frontend:prod      # explicit app and environment

env_files

env_files controls which local files ev reads when you run push, pull, diff, or scan. Files are merged in order — later files take precedence over earlier ones when the same key appears in multiple files.

ev init generates the default:

env_files:
  - .env
  - .env.local

Framework Examples

Next.js — include all Next.js env file layers:

env_files:
  - .env
  - .env.local
  - .env.development.local

Vite — include mode-specific files:

env_files:
  - .env
  - .env.local
  - .env.development
  - .env.development.local

Docker / production — target a single file:

env_files:
  - .env.production

Monorepo per-app — each app entry in ev.yaml can have its own env_files list:

apps:
  frontend:
    path: packages/frontend
    env_files:
      - .env
      - .env.local
  backend:
    path: packages/backend
    env_files:
      - .env
      - .env.production.local

Backend Config

project: clxxxxxxxxxxxxxxxxxxxxxxxx
name: my-project
default_env: dev
 
backend:
  type: aws-secrets-manager
  region: us-east-1
  prefix: /myapp/

See Storage Backends for all backend types and options.

Per-Environment Backend Override

Keep dev on ev's encrypted storage while prod uses AWS Secrets Manager:

project: clxxxxxxxxxxxxxxxxxxxxxxxx
name: my-project
default_env: dev
 
backend:
  type: aws-secrets-manager
  region: us-east-1
  prefix: /myapp/
 
environments:
  dev:
    backend:
      type: ev

Context Resolution

When you run an ev command, it resolves context in this order:

1. Explicit argument — ev push backend:staging sets app to backend, env to staging
2. Partial argument — ev push staging sets env to staging, app from cwd or ev.yaml
3. Working directory — if cwd matches an app path in ev.yaml, that app is used
4. default_env — from ev.yaml
5. Global default — dev

Worktrees

Controls where ev worktree add creates worktrees.

worktrees:
  dir: .worktrees   # default

This block is entirely optional — omitting it is the same as setting dir: .worktrees. The directory is added to .gitignore automatically on first use.

See ev worktree for full usage.

Local Files

ev stores per-user state in ~/.config/ev/:

These files are created automatically and should never be checked into version control. ev adds them to .gitignore during ev init.