@nilejs/cli

Create Nile Js projects and generate services, actions and schemas.

Create a project

bunx @nilejs/cli new my-app
cd my-app
bun install
cp .env.example .env
bun run dev

The server starts on http://localhost:8000. The starter stores its data in an embedded PGlite database, so there is no database server to install. The getting started guide walks through the starter step by step.

The starter includes:

• src/index.ts: server entry point on Bun's native HTTP server, with a logger and an onBoot schema push
• src/db/: PGlite and Drizzle client, the tasks table and a taskModel built with createModel
• src/services/: an explicit registry and domain entry point for a tasks service with create, list, get, update and delete actions
• Dockerfile, docker-compose.yml and docker-compose.dev.yml for container deployments
• drizzle.config.ts, .env.example, tsconfig.json and package.json

Generate code

Run the generators from the project root. The starter's gen script calls the CLI for you.

generate also has the alias gen, so bunx @nilejs/cli gen service users works outside the starter.

Services

bun run gen service users

Creates:

src/services/users/
  actions/sample.ts   Sample action with a schema, an input type and a named handler
  index.ts            Registers the service and its public actions

The CLI then asks whether to register the service in src/services/services.config.ts. If you decline, it prints the lines to add yourself.

Actions

bun run gen action users get-user

Creates src/services/users/actions/get-user.ts:

import { createAction } from "@nilejs/nile";
import { Ok } from "@nilejs/nile/fp";
import z from "zod";

const getUserSchema = z.object({
  // Describe the input this action accepts
});

type GetUserInput = z.infer<typeof getUserSchema>;

const getUserHandler = async (input: GetUserInput) => {
  // Implement users.get-user here
  return Ok({ result: input });
};

export const getUserAction = createAction<GetUserInput>({
  name: "get-user",
  description: "GetUser action for users",
  validation: getUserSchema,
  handler: getUserHandler,
});

Kebab-case names become camelCase variables and PascalCase types. Register the action by importing it in src/services/users/index.ts and adding it to the service’s actions list. The root registry imports services, not individual actions.

Schemas and types

bun run gen schema

Reads every action's validation schema from src/services/services.config.ts and writes:

• src/generated/schemas.ts: named Zod schemas, such as tasksCreateSchema
• src/generated/types.ts: input types, such as TasksCreatePayload

Every registered action is included in ServicePayloads. Actions without a validation schema accept an object payload (Record<string, unknown>), so actions such as tasks.list can be called with {}. This fallback does not add server-side validation. Schemas that cannot be converted are reported separately. Share the generated files with a frontend to validate forms with the same rules as the server.

Current starter

CLI 1.0.2 targets Nile ^1.0.4, Zod 4, TypeScript 7 and the Drizzle model helpers. The generated layout passes Nile’s strict boot checks. Database setup returns a Result and prevents startup on failure; shutdown drains Nile’s work before closing PGlite. Helpers are available as utils.createModel, and Result helpers come from @nilejs/nile/fp.

Existing apps are not rewritten when the CLI updates. For an older starter, add a service entry point at src/services/<domain>/index.ts, register its actions there, and import that service from services.config.ts. Nile’s migration notes describe the current error and startup behavior.

Coding assistants

The starter includes SKILL.md with the current Nile action pattern, service layout, Results, access policies and client calls. Ask your assistant to read it before changing the backend. After updating Nile, use the version shipped at node_modules/@nilejs/nile/SKILL.md.

Requirements

• Bun 1.4.2 or later. The starter runs on Bun, and gen schema imports your services with Bun.

License

MIT