CLI Reference
Automate your workflow. The Caspian CLI handles scaffolding, database code generation, and framework updates.
Project Creation
Initialize a new project using the interactive wizard or command-line flags.
Installation Flags
| Flag | Description |
|---|---|
| --backend-only | Skips all frontend assets (CSS/JS). Ideal for pure JSON APIs. |
| --tailwindcss |
Installs Tailwind CSS v4, PostCSS, and configures
globals.css.
|
| --typescript |
Adds TypeScript support with Vite, including
tsconfig.json.
|
| --mcp | Initializes a Model Context Protocol server for AI Agents. |
| --prisma | Initializes a Prisma ORM setup. |
Full-Stack (Default)
Includes Tailwind, Prisma, and all frontend assets.
Custom Source
Install from any Git repository.
Project Scripts
Once a project exists, day-to-day work runs through its
package.json
scripts. Confirm a script is actually defined in the project before
recommending it — the generated set depends on the enabled features.
| Script | What it does |
|---|---|
| npm run dev |
Starts the local stack: the Python server, BrowserSync, and the CSS
watcher. Start it only when the task needs the running workflow —
it recreates .casp/
and rebinds ports, so never launch a second one beside a session that
is already running.
|
| npm run build | Deployment prep: the one-shot CSS build plus the regenerated route and component index. Not a validation step for routine edits. |
|
npm run css npm run css:build |
Compiles src/app/globals.css
into public/css/styles.css
— watch and one-shot. You rarely run either directly:
dev already
runs the watcher and
build the
one-shot.
|
|
npm run test npm run test:fix |
Quality gate Type check, lint, template validation, and tests in one pass with one exit code; the :fix
companion formats and applies safe fixes first. There is no separate
lint,
typecheck, or
check script,
and a bare pytest
run is not the gate. See
Testing & Quality Gate.
|
|
npm run format npm run format:check |
Formats authored markup then Python, in that order. See Formatting. |
| npm run logs | Per-route browser health for the active dev session. See Browser Logs. |
|
npm run static npm run static:serve |
Exports every static route to
static/, and
previews that folder over HTTP. See
Static Export.
|
|
npm run down npm run up npm run maintenance:status |
Turns maintenance mode on (npm run down -- --with-secret
prints a bypass URL), off, or reports its state. See
Maintenance Mode.
|
Code Generation
Automatically generate strict
Python Data Classes (Pydantic) based on your
prisma/schema.prisma
definition.
Update Project
Warning: File Overwrites
Executing
npx casp update project will
download the latest framework core. By default, this
overwrites config files and entry points. To preserve
your custom work, you must configure the
excludeFiles
array in config.
Configuration
The
caspian.config.json
file controls how the CLI interacts with your project and handles updates.
"projectName": "caspian-web", "projectRootPath": "./", "backendOnly": false, "tailwindcss": true, "mcp": false, "websocket": false, "prisma": false, "typescript": false, "version": "latest", "componentScanDirs": [ "src" ], "excludeFiles": [ "./.env", "./src/app/globals.css", "./src/app/index.py" ]
excludeFiles Strategy
The example above protects your environment variables, styles, and configuration from being reset during a framework update.