◆ KOVO
Star
Menu

API Reference

View as Markdown

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

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>`
`--dialect <postgres sqlite>`
--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]`
--no-install Alias for --install=never.
`--deployment <node vercel
`--retention <unconfigured retained-24h>`
--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.