Getting Started

Quickstart

Define your first product entity, run Vadyl locally, hit your first compiled API. Under ten minutes.

This walkthrough takes you from an empty machine to a running backend with a compiled REST + GraphQL + SDK surface, signed in as an authenticated user, hitting a real database. Coffee not required.

1. Install the CLI

npm install -g @vadyl/cli
# or
brew install vadyl

Verify the install with vadyl --version. The CLI is the canonical control surface for everything you can do via the API or the dashboard — same endpoints, same auth, same outcomes.

2. Sign up and create a project

vadyl auth login
vadyl projects create my-app --region us-east-1

Projects are sovereign data-plane units. Each one is a self-contained backend instance with its own provider bindings, lifecycle, billing scope, and capability grants. You can nest projects later for multi-tenant or multi-environment topologies.

3. Define your first entity

Create a file schema/Order.vadyl.ts:

import { entity, field, relation } from "@vadyl/sdk";

export const Order = entity("Order", {
  id:        field.id(),
  total:     field.decimal({ precision: 10, scale: 2 }),
  currency:  field.string({ maxLength: 3 }),
  status:    field.enum(["pending", "paid", "fulfilled", "refunded"]),
  customer:  relation.belongsTo("Customer"),
  createdAt: field.timestamp({ defaultsTo: "now()" }),
});

That's the first piece of your product model. Not a SQL migration, not an ORM model — a canonical entity contract. Vadyl will compile this into the right DDL for whichever database you bind, generate typed SDK clients, expose it on REST + GraphQL + gRPC, and wire it into the dashboard.

4. Deploy it

vadyl deploy

The CLI runs schema diff, classifies the migration, and applies it through the canonical schema-transition pipeline. You see the planned DDL before anything executes. If it's safe, it auto-applies; if it needs backfill or carries destructive risk, you get an explicit approval prompt.

5. Hit your APIs

# REST
curl https://api.vadyl.app/v1/orders \
  -H "Authorization: Bearer $VADYL_TOKEN"

# GraphQL
curl https://api.vadyl.app/graphql \
  -H "Authorization: Bearer $VADYL_TOKEN" \
  -d '{"query":"{ orders { id total status } }"}'

# Typed SDK
import { vadyl } from "@my-app/sdk";

const orders = await vadyl.orders.list();

Every shape — REST, GraphQL, gRPC, the typed SDK — is compiled from the same product model. They never drift.

What's next

Define richer entities with relations, validation, access policies.
Add access policies so users only see their own data.
Wire a workflow for orders that need long-running orchestration.
Deploy to production with branches, sandboxes, and progressive rollouts.

Introduction

Local development