CLI Reference

Dawn ships a single dawn binary with eight commands: build, check, dev, routes, run, test, typegen, and verify. Most commands read dawn.config.ts from the current working directory or from --cwd <path>; dawn dev currently uses the current working directory and exposes only its own server flags.

dawn check

Validates the app structure and configuration.

dawn check

Internally, dawn check loads dawn.config.ts, resolves the app root, runs discoverRoutes, and parses each route's tool definitions with discoverToolDefinitions. It surfaces:

• A dawn.config.ts that fails to load.
• Any discovered route whose index.ts exports more than one of agent, workflow, graph, chain.
• Any tool file that fails to parse.

Output is a Dawn app is valid: N routes discovered. line followed by a per-route - <pathname> (<kind>) summary. Exits non-zero on any violation with a detailed message.

dawn verify

Runs four checks in one call (app, routes, typegen, deps) — the canonical pre-deploy integrity gate.

dawn verify
dawn verify --json

Flags:

• --cwd <path> — operate on a different app root.
• --json — emit a structured report ({ status, appRoot, checks, counts }) instead of human-readable text.
• --env-file <path> — path to a .env file (overrides dawn.config.ts env and the default ./.env).

The deps check covers missing packages and missing env vars (advisory) — uniquely useful before a deploy. See Deployment for the recommended workflow.

dawn routes

Lists every route Dawn discovered and its computed pathname.

dawn routes
dawn routes --json

Output:

Discovered 2 Dawn routes in /path/to/app
/hello/[tenant] -> src/app/(public)/hello/[tenant]/index.ts
/admin/users -> src/app/(internal)/admin/users/index.ts

Use this to confirm that route groups and dynamic segments are being parsed the way you expect.

dawn typegen

Regenerates .dawn/dawn.generated.d.ts plus per-route .dawn/routes/<routeSlug>/tools.json and .dawn/routes/<routeSlug>/state.json manifests.

dawn typegen

The success log reports route, tool-schema, and stateful-route counts. The tools.json artifacts are consumed by dawn build to emit LangGraph entries.

dawn build

Writes .dawn/build/langgraph.json plus per-route entry files under .dawn/build/<routeSlug>.ts — the artifacts you hand to LangSmith.

dawn build
dawn build --clean

Flags:

• --cwd <path> — operate on a different app root.
• --clean — wipe .dawn/build/ before writing.

The generated langgraph.json includes graphs (keyed by <routeId>#<kind>), dependencies: ["."], env (.env.example if present, else .env), and node_version: "22". For agent routes, the generated entry imports the default agent() descriptor, materializes it as a LangGraph graph, and wires in every discovered route tool.

See Deployment for the full bridge.

dawn run

Executes a single route invocation with JSON stdin/stdout.

echo '{"tenant":"acme"}' | dawn run '/hello/[tenant]'

Flags:

• --cwd <path> — operate on a different app root.
• --url <url> — run against a live dev server instead of the in-process runtime.

The route argument can be the parameterized id (/hello/[tenant]) or the relative route entry file path (src/app/(public)/hello/[tenant]/index.ts). Dynamic segment values come from the JSON input.

dawn test

Runs every colocated run.test.ts scenario in the app.

dawn test
dawn test src/app/(public)/hello

Flags:

• --cwd <path> — operate on a different app root.

The optional positional [path] argument narrows the discovered scenario set to a subdirectory. To target a live dev server, set run: { url } per-scenario inside run.test.ts (there is no command-level --url flag on dawn test). Exits non-zero on any failure with a diff per mismatched scenario. See Testing for scenario authoring.

dawn dev

Starts the local runtime — hot reload + LangSmith protocol. Bind address is fixed at 127.0.0.1.

dawn dev
dawn dev --port 3001

Flags:

• --port <n> — HTTP port. Default: dynamically allocated. Pass --port for a stable address.
• --env-file <path> — path to a .env file (overrides dawn.config.ts env and the default ./.env).

See Dev Server for the full protocol reference and architecture notes.

Exit codes

Non-zero exit codes from underlying tools (Commander, child processes) may be propagated unchanged.

Related