CLI

Run kitr with pnpm kitr <command>, or pnpm dlx @kitr/kitr <command> without installing. Every command runs from flags alone; nothing prompts.

A global install (pnpm add -g @kitr/kitr) lets you type kitr directly. Inside a project it hands over to the project's own copy, so the version in package.json is the one that edits your files. KITR_GLOBAL=1 skips the handover.

Project commands

Create a project

Kits: blank, app, fullstack, server, and the presets saas, site, realtime, desktop, tauri and mobile. Kits shows what each one writes.

Add a package

kitr add installs the package, registers its provider in kitrrc.ts, writes config/<pkg>.ts and updates AGENTS.md. It also adds the packages it needs: adding api adds server and logger.

Questions a package asks are flags: kitr add jobs --no-worker. --yes takes the defaults, and kitr add <pkg> --help lists the questions. --dry-run shows the changes without writing them.

Any npm package with a kitr setup module works: kitr add @acme/stripe. See Package contract.

Check and upgrade

kitr doctor checks kitrrc.ts against package.json, missing config files, imports that should go through an @kitr/* package, and versions that drift from the tested set. --json prints the result for scripts; --strict turns warnings into errors.

kitr upgrade also moves upstream libraries to the versions that kitr release was tested with. It lists major bumps without applying them; --majors applies them.

Platforms

To pick a few, list them (kitr build admin api) or use --filter=admin,api. Both do the same thing.

With more than one platform, kitr dev prefixes each line with the platform's name ([site]). KITR_<NAME>_<OPTION> overrides any option at run time: KITR_SITE_PORT=4000 kitr dev site.

The server without Vite imports config/index.ts, which kitr add regenerates. When a platform has a config/<platform>/ folder or a without list, that file picks the build's object with forBuildPlatform(); see Config per platform.

Workspaces

A repository with several kitr apps lists them in kitr.workspace.ts at its root:

// kitr.workspace.ts
import { defineWorkspace } from '@kitr/kitr'

export default defineWorkspace({
  apps: { www: 'apps/www', app: 'apps/app', phone: 'apps/phone' },
})

Each app is a complete kitr project with its own kitrrc.ts. Shared code goes in ordinary workspace packages.

Inside an app directory every command is the app's own, as if there were no workspace.

Generators

kitr make:<kind> <name> writes one file and registers it where it belongs. kitr make lists the generators your project has.

A nested name makes a folder: make:controller admin/users writes server/controllers/admin/users-controller.ts. --dry-run shows what would change, and --force overwrites a file. To change a template, kitr eject stub <kind> copies it to stubs/<kind>.ts. Project structure explains where each kind of file lives.

A package can add its own generators. See Building packages.

Components

Components come from kitr's own registry. To use another shadcn-format registry, pass --registry <url\|path> or set KITR_REGISTRY.

API and server

Type generation

kitr generate writes the project's generated files: types under .kitr/ (ignored by git), each package's own files, such as the API route table, then the app's own steps from generate in kitrrc.ts. You rarely run it yourself: kitr dev, kitr build, kitr new and kitr add run it, and the dev server reruns it when a file changes.

Add your own step

An app adds a step of its own, such as a content index, under generate in kitrrc.ts. run is a shell command or a function:

// kitrrc.ts
import { defineKitrConfig } from '@kitr/kitr/app'

export default defineKitrConfig({
  packages: [],
  providers: [],
  generate: [{ name: 'content', run: 'node scripts/content.mjs', watch: ['content/**/*.md'] }],
})

It runs after the type generators and the package steps, in kitr generate, kitr dev, kitr build and kitr typecheck, and kitr doctor lists it. Add your own code has the details.

Add a type generator to a package

A package adds a generator with defineTypes() and points its setup module at it with the types hook:

// packages/<name>/src/types.ts
import { defineTypes } from '@kitr/core'

export default defineTypes({
  name: 'channels',
  watch: (rc) => [`${rc.directories.app ?? 'app'}/channels/**/*.ts`],
  generate: (ctx) => [{ file: 'channels.d.ts', content: render(ctx.glob('app/channels', '**/*.ts')) }],
})

// packages/<name>/src/kitr.ts
import { definePackage } from '@kitr/core/package'

export default definePackage({
  name: 'channels',
  add(ctx) {
    ctx.types.enable()
  },
  types: () => import('./types'),
})

generate returns { file, content } pairs relative to .kitr/, and the runner writes them. watch lists the files that rerun it in dev.

Leaving kitr

kitr eject stubs copies every generator template into your project. kitr eject all also prints the import rewrites that remove kitr: each kitr/* import maps to the library it re-exports.