@b4run/cli
Command-line development tools and runtime embedding entry points for B4.run applications.
Use this when: You are developing, checking, testing, building, serving, or embedding a B4.run runtime.
▶ Watch the 50-second navlog demo
Install
Requires Node.js 24 or later. create-b4-app adds the CLI to a new app for you. To add it to an existing app, install it as a regular dependency, not a dev dependency, because the server that b4 build emits imports @b4run/cli at runtime:
npm install @b4run/cli
Example
Run the local b4 binary through npx or a package.json script:
npx b4 dev
npx b4 check
npx b4 test
npx b4 build
| Command | What it does |
|---|---|
b4 dev | Starts the local development runtime with hot reload on 127.0.0.1. |
b4 check | Validates the app's structure and configuration. |
b4 verify | Checks the app, routes, generated types, dependencies, provider keys and Node version before you run or deploy. |
b4 typegen | Regenerates the route and tool types under .b4/. |
b4 test | Runs the app's colocated run.test.ts route scenarios. The starters' npm test runs vitest instead. |
b4 build | Generates deployment artifacts: a Node server, Dockerfile and LangSmith config by default. |
b4 start | Serves the app in production, on 0.0.0.0:8000 by default. |
b4 docs | Prints the B4.run docs bundled with the installed CLI. |
The CLI guide lists every command and flag.
b4 start serves the app without any code of your own. To let application code own the production Node listener instead, import serveRuntime from the package root:
import { serveRuntime } from "@b4run/cli"
const runtime = await serveRuntime({
appRoot: process.cwd(),
host: "0.0.0.0",
port: 8000,
})
console.log(runtime.url)
// Call await runtime.close() during your host's ordered shutdown.
Runtime and stability
@b4run/cliand itsb4command are supported node-only application and tooling surfaces.@b4run/cli/fetchis a supported edge-safe integration surface for generated fetch deployments.@b4run/cli/runtimeis Node-only and low-level.@b4run/cli/workspaceis Node-only and low-level: managed-workspace lifecycle for a host process, without the command program.@b4run/cli/testingis a deprecated, back-compat-only node-only alias of@b4run/sdk/testing; it remains supported only for existing imports, and new scenario code should use the SDK subpath.
serveRuntime() starts once and does not watch files or run type generation at boot. Use b4 dev for the development watcher and generated types.
Usage reporting
The development-time commands (dev, build, add, check, typegen, verify, eval) report an anonymous usage signal when they finish: the command name, CLI version, Node major version, operating system, outcome, a coarse duration bucket, and an error class on failure. b4 dev also reports one activation signal the first time an AG-UI run finishes in a session, carrying only the CLI version and the route kind. b4 start, the runtime packages, and create-b4-app never report, and nothing about your routes, models, prompts, paths, or identity is sent. The first reporting command prints a one-time notice to stderr and creates a random id in ~/.b4/usage-id. CI and hosted build environments (GitHub Actions, Vercel, Render, Cloudflare Pages, and others) are silent automatically; see b4.run/privacy for details.
| Variable | Effect |
|---|---|
B4_TELEMETRY_DISABLED=1 | Turns usage reporting off. |
DO_NOT_TRACK=1 | Turns usage reporting off. |
B4_SIGNALS_URL | Overrides the URL signals are posted to. |
B4_SIGNALS_URL is read from the shell environment once at startup, never from a project .env. The two opt-out variables are honoured from the shell before anything happens, and from a project .env for every send; a project .env loads after the command starts, so on the very first run the id file and the notice can still appear before it takes effect.
Related
@b4run/sdksupplies the route and runtime contracts consumed by the CLI.@b4run/coreprovides the route discovery, configuration, and type-generation primitives used by the CLI.- CLI guide
- CLI API reference
- Embed the runtime
- Deployment options
@b4run/clichangelog
Maturity and support
B4.run is pre-1.0, and its public surface can change. All publishable B4.run packages release together as a fixed group; review the @b4run/cli changelog and upgrading guide before upgrading. For support, use GitHub Discussions; report defects in GitHub Issues.
License
MIT. See the repository license.
Shared Postgres execution
Generated Vercel and Hono Postgres deployments coordinate run ownership across
instances. Another request executing the same thread receives HTTP 409
run_in_flight with Retry-After: 1; a browser-tool continuation holds the same
ownership boundary while accepting results and resuming the graph. Successful
terminal events are sent after final writes and ownership release, so a client
can immediately submit the next turn.
For custom fetch embeddings, provide one RequestStores.runAdmission per request
and construct its checkpoint, thread, permission and client-tool stores with the
admission's fenced pool. See the Postgres storage package
for the API and transaction limits. Sharing durable stores alone does not
coordinate execution; the default in-memory registry is local to one handler.
This does not add distributed AP cancellation or exactly-once external tool effects.