Vadyl
CLI

Your product model, from the terminal.

The Vadyl CLI is a standalone executable for defining and operating the things your product is built around: entities, permissions, workflows, branches, deploys, runtime scaling, agents, explainers, and project-published command surfaces. Same product model as the dashboard, SDKs, APIs, and MCP. Configure once via environment variables; run anywhere.

Read the docsCLI reference
terminalsh
bash
$ vadyl status
  Tenant       acme
  Project      orders-prod
  Branch       main
  Publication  v8421 · 2026-05-06T11:42Z
  Surfaces     REST · GraphQL · gRPC · MCP

$ vadyl entity list
  Customer        12 fields  · 3 relations
  Order           18 fields  · 4 relations
  Product         24 fields  · 2 relations

$ vadyl branch sandbox add-tax-fields
  ✓ Sandbox provisioned · isolated DB ready
  ✓ Branch checked out
Install

One executable. Every platform.

macOS / Linuxsh
# Homebrew
brew install vadyl/tap/vadyl

# Or via curl
curl -fsSL https://vadyl.dev/install.sh | sh

# Or npm
npm install -g @vadyl/cli
Windowspowershell
# winget
winget install vadyl

# Or PowerShell
irm https://install.vadyl.dev/windows.ps1 | iex

# Or npm
npm install -g @vadyl/cli
Reference

Exact command contracts

The CLI guide shows workflows; the reference pages are the authoritative contract for commands, flags, output, exit codes, and automation behavior.

CLI

CLI command reference

Every command group, subcommand, flag, sample output, and exit code for automation and CI.

Open reference
CLI

CLI reference model

How commands project from the canonical operation model, auth scope, output contract, and exit behavior.

Open reference
Surfaces

Project capability surfaces

Project-authored, project-published, project-installed capability surfaces across manifests, grants, exposure bindings, PCG, SDK, CLI, MCP, and usage evidence.

Open reference
Coding

Coding environment reference

Workspace commands, runtime SDK surfaces, source assets, tests, deploys, and local execution.

Open reference
REST

REST controller atlas

Every controller-backed endpoint with parameters, request examples, responses, errors, and samples.

Open reference
Errors

Errors reference

Canonical error envelopes, HTTP status mapping, machine-readable codes, reason codes, and correlation IDs.

Open reference
Limits

Limits & quotas

Rate limits, hard and soft quotas, budget enforcement, usage metering, and retry guidance.

Open reference
Configuration

Environment-first

Set once in your shell or CI; every CLI invocation picks them up. Per-call flags override env.

~/.zshrcsh
# Required
export VADYL_URL="https://api.vadyl.app/v1"
export VADYL_TOKEN="$(vadyl auth token)"     # bearer
# OR API-key auth for machines:
export VADYL_API_KEY="va_..."
export VADYL_API_SECRET="..."

# Tenant + project scope
export VADYL_TENANT="acme"
export VADYL_PROJECT="orders-prod"

# Optional — pin to a feature branch
export VADYL_BRANCH="feature/refunds"

# Optional — non-interactive mode for CI
export VADYL_NO_TTY=1
Command groups

Every product surface, every flow

The CLI is organized around the same canonical product model as the rest of Vadyl. Each group has subcommands, flags, and JSON output for piping into jq / shell scripts / CI.

auth

login, logout, token, whoami, switch, set-tenant. Token caching with refresh-token families.

entity

list, get, create, update, delete, diff, preview, fields, relations, indexes.

schema

diff, preview, apply, snapshot, restore, validate. Schema-transition classification.

branch

create, list, switch, sandbox, propose, merge, status, head, log.

sandbox

create, apply, destroy, list, seed. Real DB isolation per branch.

proposal

open, list, approve, request-changes, merge, validation. Branch protection policies.

deploy

preview, apply, rollback, status, history. Ramp policies, bake times, health gates.

runtime-fabric

topology, health, plan, apply, reconcile, drain, scaling preview, desired count, resources, ingress, autoscale explain.

build

Hermetic builds for authored runtime artifacts. Deterministic, signed. Pin a publication.

publication

list, get, lineage, current, set-current. Project runtime publication history.

project

list, create, archive, suspend, resume. Hierarchy, federation, delegation.

connection

Manage governed connections. Test connectivity. Inspect secret references and capabilities.

secret

list, set, rotate, reveal (with audit). Key-ring backed; no raw strings on disk.

agent

List, inspect, run agents. Check token budgets. Tail runs in real time.

workflow

Start, signal, query, list runs, replay, cancel. Same surface as the SDK.

events

tail, replay, search. Filter by entity, type, time, correlation.

audit

tail, search, replay. Filter by reason code, actor, entity, scope.

explain

access, read-plan, project-runtime, authored-publication. Canonical decision reasoning.

sdk

Generate language SDKs. Inspect manifests. Verify generated-format compatibility.

surface

Publish, validate, install, upgrade, grant, consume, explain, and revoke project capability surfaces - including project-authored CLI commands.

Reference

Common workflows

0. loginsh
# Interactive (browser-based OIDC)
vadyl auth login

# Or programmatic with API key (for CI)
vadyl auth login --api-key "$VADYL_API_KEY" --api-secret "$VADYL_API_SECRET"

# Verify
vadyl auth whoami
vadyl status
1. inspect a projectsh
# List projects you can see
vadyl project list

# Switch scope
vadyl project use orders-prod

# Inspect entities
vadyl entity list
vadyl entity get Order --include relations,indexes
vadyl entity get Order --output json | jq '.fields[] | .name'
2. propose a schema changesh
# Branch + sandbox
vadyl branch create feature/refunds
vadyl sandbox create --branch feature/refunds --seed snapshot:latest

# Edit your schema files locally...
vadyl schema diff
vadyl schema preview --target sandbox

# Open a proposal against main
vadyl proposal open --title "Add refund tracking" --base main --head feature/refunds
3. ship to productionsh
# Preview what will change
vadyl deploy preview --target production

# Apply with a ramp policy
vadyl deploy apply --target production \
  --ramp 5%,25%,50%,100% --bake 10m

# Watch the rollout
vadyl deploy status --target production --follow

# Roll back (forward — never destroys data)
vadyl deploy rollback --target production --to v412
4. scale a runtime surfacesh
# Preview canonical topology/resource/ingress changes
vadyl runtime-fabric scaling preview --project orders-prod --file runtime-topology.json

# Set an autoscale policy for a surface
vadyl runtime-fabric scaling set-policy --project orders-prod --surface EventConsumer --file autoscale.json

# Explain the latest autoscale decision or rejection
vadyl runtime-fabric autoscale explain --project orders-prod --env production --surface EventConsumer
5. tail and explainsh
# Tail canonical event stream
vadyl events tail --filter "kind=order.paid"

# Tail audit (typed reason codes)
vadyl audit tail --filter "reasonCode startsWith 'Access.Denied'"

# Explain a specific decision (canonical, not log-derived)
vadyl explain access --entity Order --filter "id=ord_abc" --as user:abc
vadyl explain read-plan --entity Order --include relations
vadyl explain project-runtime
6. agents from the terminalsh
# Run an agent
vadyl agent run SupportAgent --prompt "Refund order #12345 due to defect"

# Tail an in-flight run
vadyl agent runs tail <runId>

# Inspect plan + tokens + reasoning
vadyl agent runs show <runId> --output json | jq '.plan'
vadyl explain agent-run <runId>
7. publish and install a project command surfacesh
# Provider project publishes a surface that includes CLI commands
vadyl surface validate ./vadyl.surface.ts
vadyl surface publish RevenueOps@2.4.0 --manifest ./vadyl.surface.ts

# Consumer project installs and narrows grants
vadyl surface install RevenueOps@2.4.0 \
  --publisher acme/revenue-ops \
  --grant cli:revenue.reconcile \
  --grant operation:ledger.reconcile

# Installed command appears through the same CLI authority
vadyl revenue reconcile --period 2026-04 --output json
vadyl surface consumption RevenueOps --group-by operation,consumerProject
Output formats

Pipe everything

Every command supports --output (table | json | yaml). JSON output is stable and versioned — safe for scripting.

json outputsh
vadyl entity get Order --output json \
  | jq '.fields[] | select(.required) | .name'

vadyl events tail --output json \
  | jq -r 'select(.kind == "order.paid") | .entityId'
exit codessh
# 0   success
# 1   generic error
# 2   invalid arguments
# 3   not found (entity, branch, run, …)
# 4   access denied
# 5   conflict (CAS mismatch, branch protected, …)
# 6   quota exceeded
# 7   network / unavailable
# Use $? in shell for fine-grained CI handling
Help

Discover everything from the CLI itself

discoverysh
vadyl --help                  # top-level command groups
vadyl entity --help           # group's subcommands and flags
vadyl entity get --help       # subcommand's flags + examples
vadyl version                 # CLI version + manifest compatibility window

Put product-model changes in your CI pipeline.

The CLI is the same surface the dashboard uses. Anything you can model, branch, deploy, explain, or audit in the UI can run in CI.

CLI referenceRead the docs

Explore the platform

SDKs

Typed product model access from application code, in five languages.

APIs

REST, GraphQL, gRPC, Realtime, MCP — every product surface.

Branching

Sandbox + propose + merge — the workflow the CLI exposes.