.ov.yaml

.ov.yaml is an optional project config file that lives in your repository root. When present, ov run, ov mcp serve, and every other CLI entry point auto-detect it by walking up from the current working directory — so you don’t have to pass --app / --env on every command.

It’s safe to commit — the file contains only app/env slugs and secret names, never secret values.

Format

# OpaqueVault project config. Safe to commit — contains no secret values.

app: my-saas          # app slug in OpaqueVault
env: production       # environment slug inside that app

# Optional: which secrets to inject with `ov run` and vault_run.
# If omitted, all secrets in the (app, env) are injected.
secrets:
  - DATABASE_URL
  - STRIPE_SECRET_KEY
  - SENDGRID_API_KEY

All three fields are optional. A file with only app set is valid — the env will fall through to your config default (ov env use) or production.

Discovery

.ov.yaml is found by walking up the directory tree from your current working directory until one of:

A .ov.yaml is found — that file wins.
Your home directory is reached without finding one — no project config, falls through to the next rung in the resolution chain.

The first .ov.yaml on the walk up wins. Nested project trees (monorepos with per-package configs) can ship their own .ov.yaml at each level; the closest one to the working directory is used.

Resolution chain

.ov.yaml fits into the fixed priority order the CLI uses to resolve (app, env) on every command:

Explicit flags — --app / --env on the command line always win.
.ov.yaml — project config from the walk-up.
Config defaults — your global defaults from ov app use / ov env use, stored in ~/.config/ov/config.toml.
Hard defaults — the default app, production env fallback.

Run ov status any time to see which rung won and — if .ov.yaml was the source — the absolute path to the file that supplied the value.

Typical layout

my-saas/
├── .ov.yaml              # app: my-saas, env: production
├── .git/
├── package.json
└── src/...

Once the file exists, every command in the tree targets my-saas / production without flags:

ov secret list             # lists my-saas/production secrets
ov run -- ./migrate        # injects DATABASE_URL + STRIPE_SECRET_KEY + SENDGRID_API_KEY
ov status                  # confirms "Source: .ov.yaml (/path/to/my-saas/.ov.yaml)"

Override any field for a single command:

ov secret list --env staging

Validation

.ov.yaml is parsed on every CLI invocation. If the file is corrupt or unreadable, the CLI prints a warning to stderr and falls through to the config defaults — it will never silently use a half-parsed config. Edit the file and re-run; no restart needed.

ov status — confirm which .ov.yaml (if any) is being used
ov app — manage the apps an .ov.yaml refers to
ov run — consumes the secrets: list as the default injection set