@b4run/cli

Use this when#Copy link to section: Use this when

Most apps only need the b4 command to develop, test, build, and serve. Import the package root to embed the Node server. Use /fetch when an edge adapter supplies the generated modules and the durable stores its routes need. The adapter may also pass a constructed configuration. Without one, runtime defaults apply. /runtime is low-level tooling. /workspace is the managed-workspace lifecycle without the command program, for a host process that owns its own executions. /testing is a deprecated compatibility alias.

Install and import#Copy link to section: Install and import

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

npm install -D @b4run/cli
npx b4 dev

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

npm install @b4run/cli

import { serveRuntime } from "@b4run/cli"
import { createRuntimeFetchHandler } from "@b4run/cli/fetch"

Compatibility and audience#Copy link to section: Compatibility and audience

Public exports#Copy link to section: Public exports

@b4run/cli#Copy link to section: @b4run/cli

@b4run/cli/fetch#Copy link to section: @b4run/cli/fetch

@b4run/cli/runtime#Copy link to section: @b4run/cli/runtime

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

@b4run/cli/testing#Copy link to section: @b4run/cli/testing

New scenario files should import these aliases from @b4run/sdk/testing.

@b4run/cli/workspace#Copy link to section: @b4run/cli/workspace

The package root exports the first three. This subpath lets a host process own the workspace lifecycle without importing the command program at the root.

bin:b4#Copy link to section: bin:b4

bin:b4 is the executable, 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#Copy link to section: Key contracts

serveRuntime()#Copy link to section: serveRuntime()

Embeds B4.run'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?: B4StaticModules
  readonly config?: B4Config
  readonly checkpointer?: BaseCheckpointSaver
  readonly threadsStore?: ThreadsStore
  readonly permissionsStore?: PermissionsStore | (() => Promise<PermissionsStore>)
  readonly memoryStore?: () => Promise<MemoryStore>
  readonly middleware?: B4Middleware
  readonly threadAccessExpected?: boolean
}

Fields: @b4run/cli#.:ServeRuntimeOptions

Behavior contract cli.serve.production-boot

serveRuntime starts without running type generation or writing .b4 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#Copy link to section: Runtime ownership

The /fetch handler has no filesystem fallback for its module map or its required stores, so an edge host must inject them. The host may also pass a constructed configuration. Without one, 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.

Disposable managed execution#Copy link to section: Disposable managed execution

withWorkspace(options, callback) captures options.workspace relative to appRoot, uses provider.workspaces, and invokes the callback with ordinary sandbox filesystem/command backends. Its private stateRoot retains unfinished cleanup across process restarts. One invocation may own each state directory; use separate directories for concurrent jobs. Prior unfinished work is destroyed before a fresh callback starts. Cleanup is part of completion: failures propagate and retained deletion records support retry. An independent verifier can use this instead of duplicating provider lifecycle code.

Reading a managed workspace#Copy link to section: Reading a managed workspace

withManagedWorkspaceReader({ appRoot, provider, threadId, signal }, operation) reads the workspace of a thread whose app declares sandbox.workspace. Those threads never reach SandboxProvider.acquire, so withWorkspaceReader can't address them by thread id.

The helper opens the worker's installation store under appRoot read-only, without taking the worker's owner lock. It resolves the thread's published ReadyWorkspace and passes it to provider.workspaces.openWorkspaceReader. It refuses, with the reason, when:

• the provider has no managed or read capability,
• the installation or the thread's association is missing, or
• the workspace isn't published yet (retryable), is deleted (lost), or is past its retention deadline (expired).

It never falls back to provider storage. openManagedWorkspaceReader does the same resolution without the scoped close. Both only address a workspace, so gate access in the calling process.

readThreadWorkspace(url, threadId, options, { headers, signal, expectedSourceDigest }) reads the same inventory over a worker's Agent Protocol port when the worker sets sandbox.workspaceRead: "http", for a caller that cannot reach the worker's app root. It verifies the answer's shape, thread and (when given) source digest, and throws ThreadWorkspaceReadError with the worker's status and code otherwise.

Examples and related guides#Copy link to section: Examples and related guides

import { serveRuntime } from "@b4run/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.