@dawn-ai/cli

Use this when

Most application developers use the dawn command to develop, test, build, and serve an app. Import the package root only to embed the Node server. Use /fetch when an edge adapter supplies generated modules and the durable stores its routes need; it may also supply an already-constructed configuration, while omitted configuration uses runtime defaults. /runtime is low-level tooling; /testing is a deprecated compatibility alias.

Install and import

For command-only development, install the CLI as a development dependency:

pnpm add -D @dawn-ai/cli
pnpm exec dawn dev

Install it as a runtime dependency when production code or a generated server imports the package:

pnpm add @dawn-ai/cli

import { serveRuntime } from "@dawn-ai/cli"
import { createRuntimeFetchHandler } from "@dawn-ai/cli/fetch"

Compatibility and audience

Public exports

@dawn-ai/cli

@dawn-ai/cli/fetch

@dawn-ai/cli/runtime

These exports exist for framework tooling and test harnesses. Application code should prefer root serveRuntime or the edge-safe /fetch entry.

@dawn-ai/cli/testing

New scenario files should import these aliases from @dawn-ai/sdk/testing.

bin:dawn

bin:dawn is the executable target, not a TypeScript subpath. It runs the add, build, check, dev, docs, eval, inspect, memory, routes, run, start, test, typegen, and verify commands. See the CLI Reference for command syntax.

Key contracts

serveRuntime()

Use this root export to embed Dawn's production Node server. It starts once, returns a close handle, and does not watch the filesystem.

export declare function serveRuntime(opts: ServeRuntimeOptions): Promise<ServeRuntimeHandle>

export interface ServeRuntimeOptions {
  readonly appRoot: string
  readonly host?: string
  readonly port?: number
  readonly installSignalHandlers?: boolean
  readonly modules?: DawnStaticModules
  readonly config?: DawnConfig
  readonly checkpointer?: BaseCheckpointSaver
  readonly threadsStore?: ThreadsStore
  readonly permissionsStore?: PermissionsStore | (() => Promise<PermissionsStore>)
  readonly memoryStore?: () => Promise<MemoryStore>
  readonly middleware?: DawnMiddleware
}

Fields: @dawn-ai/cli#.:ServeRuntimeOptions

Behavior contract cli.serve.production-boot

serveRuntime starts without running type generation or writing .dawn artifacts.

Behavior contract cli.serve-runtime.port-precedence

serveRuntime uses an explicit port first, then a numeric PORT value, then 8000. Empty or non-numeric PORT values also fall back to 8000; an explicit 0 still requests a random port.

Runtime ownership

serveRuntime() starts once and does not watch files or run type generation at boot. The /fetch handler has no filesystem fallback for its module map or for applicable required stores, so an edge host must inject them. Configuration may be supplied already constructed; when omitted, runtime defaults apply.

Behavior contract cli.fetch.request-store-lifecycle

A requestStores factory creates and disposes stores per request. Disposal waits for an SSE body to finish. close() waits for in-flight disposal while its bounded shutdown drain remains open; after the 30-second default deadline it warns and proceeds.

Examples and related guides

import { serveRuntime } from "@dawn-ai/cli"
 
const server = await serveRuntime({ appRoot: process.cwd(), port: 8000 })
console.log(server.url)

Continue with CLI Reference, Embed the Runtime, Edge and Hono, and Deployment Options.