CLI

The bext CLI scaffolds, runs, builds, and inspects PRISM apps. This page lists the commands used to develop an app; for the config they read, see the Config Reference.

Commands

Command What it does
bext new <name> --template <template> Scaffold a new app from a starter template.
bext dev [dir] Start the local dev server with hot reload, on 127.0.0.1.
bext build Run the build defined in the [build] section of the config.
bext run [dir] Detect the framework, build if a build is configured, then serve the app.
bext routes [dir] Print the detected routes.

dev, run, and routes take the app directory as an argument (. by default). dev and run read the bext.config.toml in that directory; build and routes read the one in the current directory.

bext new

Scaffold a new app from a starter:

bext new my-app --template @bext/starter-prism
cd my-app
bext dev

The starter is downloaded from the bext registry and its files are written to a new my-app directory. The command fails if that directory already exists. The post-install steps the starter declares (for example git init) then run; a starter can only use steps from an allowlist, never an arbitrary shell command.

Flag Effect
--template <template> Starter identifier in the registry.
--from-path <dir> Load the starter from a local directory instead of the registry (to test an unpublished starter).
--no-post-install Skip the post-install steps (informational messages are still printed).

Either --template or --from-path is required.

Starter templates

Template For
@bext/starter-prism A minimal PRISM app: JSX server components, ISR caching, one API route. The starting point for PRISM.
@bext/starter-blog A Markdown blog, with RSS feed and sitemap.
@bext/starter-docs A Markdown documentation site, with a sidebar built from the file tree.
@bext/starter-saas A SaaS app: landing page, pricing, dashboard for signed-in users.
@bext/starter-api An API-only app, with no frontend.

Only @bext/starter-prism scaffolds a PRISM app; the other four use bext's template mode (a TypeScript server in server/).

bext dev

Start the dev server on your machine, with hot reload. Changes in the app directory, the static directory, and the [build] watch_dirs are pushed to the browser: a CSS-only change is applied without reloading the page, any other change reloads the page.

The server listens on the port set by listen in the [server] section of your config, or 3061 if none is set (3000 when the directory has no bext.config.toml). If the configured host is 0.0.0.0 (or missing), it is replaced with 127.0.0.1: the server stays on loopback until you pass --listen. If the port is taken, bext dev tries the next ports and prints the one it picked. The app directory's .env file is loaded on start.

bext dev
bext dev --port 3001
bext dev --listen 0.0.0.0:8080 --open
bext dev --no-hmr
Flag Effect
-p, --port N Listen on port N, keeping the configured host (127.0.0.1 by default).
-l, --listen host:port Listen on an explicit host and port (for example 0.0.0.0:8080 to expose the server on your network). With --port as well, the port comes from --port.
--open Open the app in a browser on start.
--no-hmr Disable hot reload (no WebSocket, no script injected into pages).

bext build

Run the build configured in the [build] section of the bext.config.toml in the current directory: the script set by script (run with Bun), or Turbopack if engine = "turbopack". Tailwind CSS is generated first, unless you pass --no-css.

bext build
bext build --no-css
Flag Effect
--no-css Skip CSS generation and keep the existing styles.css.

Without script or engine = "turbopack", the command exits with an error. A PRISM app that compiles its pages on first request (on_demand = true in [compile], as in the @bext/starter-prism starter) does not need this step.

bext run

Detect the app's framework and serve it. If [build] defines a build, it runs on start; if it fails, the server still starts and the error is logged.

bext run .
bext run . --port 8080
Flag Effect
-p, --port N Listen on port N, keeping the configured host.
-l, --listen host:port Listen on an explicit host and port. With --port as well, the port comes from --port.
-w, --workers N Number of render workers.
--open Open the app in a browser on start.

Unlike bext dev, bext run keeps the configured host: with the default it listens on 0.0.0.0:3061, so on all interfaces. Without a bext.config.toml, the config is derived from the detected framework, on port 3000.

If the argument is a .ts, .tsx, .js, .mjs, .cjs, or .jsx file, bext run runs that script once instead of starting a server. Arguments after -- are passed to the script:

bext run scripts/seed.ts -- --dry-run

bext routes

Print the resolved framework for the given directory (or, without an argument, for the config's app_dir), then the page route table (pattern, dynamic or not, metadata, generateStaticParams) and the API route table with their methods and file:

bext routes
bext routes ./my-app

Related