CLI
Create an application, add files, check your work, and run development and production builds from the terminal.
Pre-setup
Use Bun 1.3.10 or later and install your application’s dependencies before running its local CLI.
Keep relkit.config.ts and the environment contract it passes to defineApp. New provider-backed
modules start with local Docker setup; the CLI itself
needs no extra defineEnv field. relkit add scaffolds selected configuration, but it does not
apply database migrations or supply secrets on your behalf.
Run commands in the right place
Use bunx create-relkit@latest in the parent directory when creating a project. Inside an installed application, use its local CLI through bun run relkit; no global installation is required.
bun run relkit --help
bun run relkit add route --help
The first command lists available commands. The second shows the arguments and flags for adding a route without writing files. In an interactive terminal, bun run relkit opens an action menu; with redirected input it prints help. Supply explicit values for automation.
Follow the application lifecycle
The generated project includes package scripts for common commands. Run these from the application root:
| Stage | Command | What happens | Continue with |
|---|---|---|---|
| Add a capability | bun run relkit add |
Choose files, their owning service, and any required packages. | Add application files |
| Validate structure | bun run check |
Check application descriptors and their relationships. | How relkit check works |
| Check TypeScript | bun run typecheck |
Check source and generated types with TypeScript. | CLI walkthrough |
| Test behavior | bun run test |
Run the application’s tests. | Testing |
| Develop | bun run dev |
Prepare the application, start the server, and watch for changes. | relkit dev |
| Build | bun run build |
Write the production output into .relkit/build. |
relkit build |
| Run the build | bun run start |
Start the built server. | relkit start |
check validates structure and runs your modules’ top-level code (what it blocks); typecheck checks types; tests verify behavior. Run all three when changing application code. Build before starting production output, and stop the development server before starting another server on the same port.
TypeScript versions
Applications type-check with TypeScript 5.9 or TypeScript 7. CI type-checks generated
applications with both. Pick one in package.json:
{
"devDependencies": {
"typescript": "7.0.2"
}
}
bun run typecheck runs that compiler, and relkit check runs the same one as a separate process.
relkit add and relkit migrate parse your source with a TypeScript 5.9 parser bundled inside
@relkit/cli, so they work with either version and never install a second typescript.
Every RelKit type rule reaches plain tsc through generated files. Keep
.relkit/generated/route-module-checks.ts in the files list of tsconfig.json: it checks route
exports and brings in the generated context and event registries. TypeScript 7 also removes
baseUrl, so write path aliases relative to the configuration, as generated projects do:
{
"compilerOptions": {
"paths": { "@app/*": ["./src/*"] },
"plugins": [{ "name": "@relkit/cli/editor" }]
},
"files": [".relkit/generated/route-module-checks.ts", ".relkit/generated/context-registry.d.ts"]
}
The @relkit/cli/editor plugin is optional. In editors that load TypeScript 5.9 plugins it shows
route export errors while you type, before you save and run relkit check. Removing it, or using
TypeScript 7, whose editor support does not load plugins, changes no check result: the same errors
appear from tsc, bun run typecheck and relkit check.
Choose a practical task
Create, add a route, and build:
follow the CLI walkthrough.
Control project creation:
choose installation and Git options.
Add services, functions, or resources:
Start Redis or MinIO:
follow Local Docker; these commands manage declared local resources separately from the backend.
Apply database migrations:
follow Migrations.
Generate a frontend client:
follow Generated clients.
Prepare a deployment:
follow Deployment, starting with local Docker and the supported provider paths.
Build an editor integration:
use the programmatic tooling APIs.
For the longer Orders application, continue through Learn. For flags and exact syntax, use the command reference. The separate CLI automation API reference documents JavaScript imports used by tool authors.