---
title: "create-kovo"
description: Scaffold a new Kovo app with Postgres or SQLite templates, local secrets, tests, and CI wiring.
order: 11
---

# create-kovo

`create-kovo` scaffolds a new Kovo application from the maintained starter templates. It is a public CLI package, not an app import surface.

Source: [`packages/create-kovo/src/index.ts`](https://github.com/kovojs/kovo/blob/main/packages/create-kovo/src/index.ts)

## Usage

```sh
create-kovo <target-directory> [options]
```

## Options

| Option | Description |
| --- | --- |
| `<target-directory>` | Required output directory. The command creates it when it does not exist and refuses to write into a non-empty directory. |
| `--name <name>` | Override the generated `package.json` name. Names are normalized to lowercase npm-compatible words and dashes. |
| `--example <crm|commerce>` | Clone the tracked authored sources for exactly one advanced example into a standalone packed-consumer project. No aliases or repository-only demo/test helpers are copied. |
| `--dialect <postgres|sqlite>` | Select the database starter. Defaults to `postgres`. |
| `--postgres` | Alias for `--dialect postgres`. |
| `--sqlite` | Alias for `--dialect sqlite`. |
| `--experimental-sqlite` | Required for every non-interactive `--sqlite` or `--dialect sqlite` scaffold. SQLite is a single-principal local-development scaffold, and KV447 reports that owner annotations are audit metadata rather than an engine-enforced authorization boundary. |
| `--git, --no-git` | Choose Git initialization explicitly. `--disable-git` remains a spelling alias for `--no-git`. By default, `create-kovo` runs `git init` unless the target is already inside a Git or Mercurial repository. |
| `--disable-git` | Alternate spelling for `--no-git`. |
| `--install[=auto|never]` | Run the policy-pinned `pnpm install` after scaffolding, or select `never`. `--no-install` selects `never`. Interactive use defaults to `auto`. |
| `--no-install` | Alias for `--install=never`. |
| `--deployment <node|vercel|cloudflare>` | Select the built-in deployment preset emitted into `kovo.config.ts`. |
| `--retention <unconfigured|retained-24h>` | Keep the build fail-closed with `unconfigured`, or assert the exact SPEC §14 floor with `retained-24h` only when the serving layer really retains both required artifact classes. |
| `--yes` | Use deterministic schema defaults. A target directory is still required; pass explicit flags to override any default. |
| `-h, --help` | Print usage and exit without writing files. |

## Examples

```sh
create-kovo my-app
create-kovo sales-app --example crm --yes --no-git --no-install
create-kovo shop --example commerce --yes --no-git --no-install
create-kovo my-app --yes --no-install
create-kovo my-app --name acme-todos
create-kovo my-app --deployment node --retention retained-24h
create-kovo my-app --dialect sqlite --experimental-sqlite
```

## Generated project

The scaffold writes the application source, Vite+/Kovo config, test files, README, CI workflow, and database-specific schema/auth/database files for the selected dialect. It also writes `.env`, `.env.example`, and `.gitignore`. By default, it initializes a Git repository after writing files; pass `--disable-git` to skip that step. If the target already sits under a Git or Mercurial repository, `create-kovo` leaves version control to the parent repository.
The `.env` file contains a per-project random `KOVO_CSRF_SECRET`; `.env` is gitignored, while `.env.example` keeps the deployment placeholders visible and documents the required production `BETTER_AUTH_URL`, generated-Node public-origin posture, Postgres runtime/admin URL split, PGlite data dir, and driver overrides. Framework bootstrap loads and pins that environment before generated app modules run, and the Better Auth constructors fail closed when required secrets or production origin are missing or invalid.
SQLite scaffolds are explicit opt-in: pass `--experimental-sqlite` with `--sqlite` or `--dialect sqlite`. The generated SQLite README repeats the KV447 single-principal posture: owner annotations remain visible to audits, but only Postgres/PGlite supplies the engine authorization/confidentiality boundary.

## Advanced examples

`--example crm` and `--example commerce` copy the release-authenticated authored source payload into a standalone project. The two names come from the same semantic schema as parsing and help; arbitrary paths and aliases are rejected before filesystem work.
Each packed payload accounts for every tracked source and binds copied files to byte length plus SHA-256. Repository-only scripts, scratch drivers, monorepo configs, secret-shaped files, and tests that depend on internal repository seams are excluded. The generated package, Vite/Vitest config, CI workflow, and local agent docs provide the standalone shell.

## Development host support

The technical preview policy-tests local development on Linux and macOS. Native Windows and WSL are not policy-tested development hosts in the technical preview. Generated application runtime behavior remains portable where the selected deployment preset supports it; this statement is about the scaffolded local-development journey.

## Write safety

The command resolves every template destination under the target root before writing and rejects path traversal. Existing non-empty directories and non-directory targets fail before any scaffold file is written.


## Related docs

- [Installation](/getting-started/installation/) - installing Kovo packages.
- [Project structure](/getting-started/project-structure/) - what the generated files are for.
- [The Kovo CLI](/guides/cli/) - day-to-day project commands after scaffolding.