KosmoJS ships two binaries.

create-kosmo bootstraps a project - you run it once, through npm create kosmo.

kosmo does everything after that. It comes with @kosmojs/cli, a devDependency of every project, and package.json wires it to scripts so you rarely type the binary name:

Script	Command	What it does
pnpm dev	kosmo serve	Dev server for every source folder
pnpm preview	kosmo preview	Production build, served and rebuilt on change
pnpm build	kosmo build	Production build
pnpm typecheck	kosmo typecheck	tsc --noEmit per source folder, plus the project root
pnpm folder	kosmo folder	Add a source folder to the project
pnpm sidecar	kosmo sidecar	Add a sidecar folder - builds, serves no HTTP

All five run from the project root - the directory holding package.json.

-h / --help prints the full usage for either binary.

The commands

Scaffolding
create kosmo	Bootstrap a new project - run once
kosmo folder	Add a source folder to an existing project
kosmo sidecar	Add a sidecar folder - entry points, no HTTP

Running a project
kosmo serve	Dev server on kosmo.devHost, Vite + HMR, always client-rendered
kosmo preview	Production build served on kosmo.previewHost, rebuilt on change
kosmo build	Production build only - dist/run.js plus a per-folder tree
kosmo typecheck	tsc --noEmit per source folder, plus the project root

Flags and prompts

npm create kosmo and kosmo folder take their answers as flags. Pass them all and the command just runs - no questions asked:

pnpm folder --name admin --frontend react --backend hono

Leave a flag out and the command asks for it instead:

• In a terminal, you get a prompt, and the command carries on with your answer.
• Without a terminal - piped output (pnpm folder | tee setup.log), a CI script, a container, an agent sandbox - there is nobody to answer, so the command stops with an error. See the messages below.

So in scripts and CI, pass every flag up front. No terminal means nobody can answer, so a run that is missing a flag fails right away instead of waiting on a question.

When a command refuses to run

Message	Cause
Unknown command; use one of folder, sidecar, serve, build, preview, typecheck	Typo, or a command from another framework's CLI.
No source folders detected	No src/*/kosmo.config.ts anywhere.
Some of the given names do not contain a valid KosmoJS source folder	A named folder doesn't exist or has no config.
No folder name provided	kosmo folder in CLI mode with no name positional - including the non-TTY case.
frontend is required: either provide --frontend <name> or --no-frontend flag	Neither half of the pair was passed.
--frontend and --no-frontend are mutually exclusive; use only one	Both halves were.
Target dir is not empty. Either remove dir contents or provide --overwrite flag	create kosmo in CLI mode, non-empty target.
./src/<name> already exists. Either remove it or provide --overwrite flag.	kosmo folder in CLI mode, folder taken.