CLI Reference

# terminal
bunx valet-dev codegen --watch

The valet-dev CLI handles project initialization, code generation, deployment, and environment variable management. All commands run locally and communicate with the orchestrator for server-side operations.

valet-dev init

# terminal
bunx valet-dev init --server https://fly.valet.host

Scaffolds a valet/ directory in the current project with a starter schema.ts and example function file. Appends _generated/ to .gitignore if present.

When --server is provided, valet-dev init registers a new project on the orchestrator (with an auto-generated name like brave-falcon-leaps) and writes the resulting VALET_PROJECT_URL and VALET_DEPLOY_KEY to a .env file in the project root. Subsequent commands like valet-dev codegen run with no flags.

Flags

valet-dev codegen

# terminal
bunx valet-dev codegen --watch

Generates typed client code from your schema and functions, and pushes them to the server.

Codegen reads valet/schema.ts and all function files, then produces typed hooks, API references, and handler registries in the output directory. If a server URL and deploy key are available, it also pushes the schema and functions to the server.

Flags

Custom directories

# terminal
bunx valet-dev codegen --valet-dir src/valet --output-dir src/_generated/valet

valet-dev deploy

# terminal
bunx valet-dev deploy

Builds and pushes schema and functions to a production project.

On first run, valet-dev deploy creates a new production project on the same orchestrator as your development project and saves credentials to .env.production. Subsequent runs push to the existing production project.

Flags

CI usage

// package.json
{
    "scripts": {
        "prebuild": "bunx valet-dev deploy"
    }
}

In CI environments (Vercel, EAS, etc.), set VALET_PROJECT_URL and VALET_DEPLOY_KEY as environment variables instead of relying on .env.production.

Credential priority

Deploy resolves credentials in this order:

1. Environment variables (VALET_PROJECT_URL, VALET_DEPLOY_KEY)
2. .env.production
3. .env

valet-dev env

# terminal
bunx valet-dev env set GITHUB_CLIENT_ID=abc123
bunx valet-dev env set GITHUB_CLIENT_SECRET secret456
bunx valet-dev env list
bunx valet-dev env unset GITHUB_CLIENT_SECRET

Manages server-side environment variables (e.g., OAuth client secrets, API keys). These variables are available to your server-side query and mutation handlers.

Subcommands

Flags

Environment variables

If a .env file exists in the project root with VALET_PROJECT_URL and VALET_DEPLOY_KEY, all commands use them as defaults. After valet-dev init --server, you can run valet-dev codegen with no flags.

Generated files

After running codegen, _generated/valet/ contains:

Always generated

Generated when functions are defined

Watch mode

# terminal
bunx valet-dev codegen --watch

In development, run with --watch to regenerate on file changes. The watcher:

1. Runs initial code generation.
2. Pushes schema and functions to the server.
3. Watches valet/ for .ts file changes.
4. Debounces rapid changes (100ms).
5. Regenerates and re-pushes on each change.

Press Ctrl+C to stop.

Server push

Codegen pushes two payloads to the server:

1. /api/functions -- handler code for server-side execution.
2. /api/schema -- table definitions, indexes, and sync configurations.

The server responds with migration status:

Pushed schema (3 tables) to server
  + Created table: comments
  + Added column todos.priority
  ~ Backfilled todos.priority (150 rows)

If there are breaking changes (type changes on existing columns), the push fails:

ERROR: Schema push failed — breaking changes detected:
  x Type change on todos.completed: number -> boolean

  Hint: Add new columns with the desired types and migrate data.

Deprecated: valet-codegen

The standalone valet-codegen binary is deprecated. Use valet-dev codegen instead -- it accepts the same flags. The old binary prints a deprecation warning and continues to work.

Troubleshooting

"schema.ts not found"

Error: schema.ts not found in ./valet

Your valet directory does not contain a schema.ts file. Verify the --valet-dir flag points to the correct directory, and that the directory contains a schema.ts file that exports a schema via defineSchema().

# terminal
ls valet/schema.ts

"Could not reach server"

Error: Could not reach server at https://fly.valet.host

The server URL is unreachable. Codegen still generates local files; only the server push fails. Check that the URL is correct and that the server is running.

# terminal
curl -s -o /dev/null -w "%{http_code}" https://fly.valet.host/health

"401 Unauthorized"

Error: 401 Unauthorized

The deploy key is missing or invalid. Set the --deploy-key flag or the VALET_DEPLOY_KEY environment variable.

# terminal
bunx valet-dev codegen --deploy-key your-deploy-key-here

"409 Conflict"

Error: 409 Conflict — breaking schema changes detected

You attempted a breaking schema change (e.g., changing a column's type from v.number() to v.boolean()). Breaking changes are not supported directly. Add a new column with the desired type and migrate data instead.

// valet/schema.ts
import { defineSchema, defineTable, v } from 'valet-dev/server'

// Instead of changing completed from number to boolean,
// add a new column and backfill it:
export default defineSchema({
    todos: defineTable({
        title: v.string(),
        completed: v.number().deprecated(),
        isCompleted: v.boolean(),
    })
        .backfill('isCompleted', (doc) => doc.completed === 1),
})