create-caspian-app

Create a new Caspian app, a high-performance Python web framework built on FastAPI and the PulsePoint browser runtime.

The installer and application tooling use Python.

Caspian is in alpha. APIs and generated project structure may change as Caspian develops.

Create an app

With uv (recommended, nothing to install first):

uvx create-caspian-app my-app

Or install the command once:

uv tool install create-caspian-app     # or: pipx install create-caspian-app
create-caspian-app my-app

You'll be asked which features you want:

? What is your project named? (my-app)
? Would you like to use Tailwind CSS? y/N
? Would you like to use MCP (Model Context Protocol)? y/N
? Would you like to use Prisma ORM (Caspian DB)? y/N
? Would you like to use WebSocket? y/N

The installer writes the project, generates a .env with fresh secrets, runs uv sync --group dev, and builds the CSS. When Tailwind is on, its compiler is the caspian-tailwind dev dependency (Tailwind's official standalone executable, one wheel per platform): uv downloads it once per machine and installs every later project from its cache, so creating an app does not download it again. Then:

cd my-app
uv run dev

uv run dev is a shortcut for uv run python main.py; both start the development server. The other everyday tools have short commands too; arguments pass through unchanged:

Skip the questions

Pass flags and -y. Only the flags you pass are turned on:

uvx create-caspian-app my-app --tailwindcss --mcp --prisma --websocket -y
uvx create-caspian-app my-app --prisma --websocket -y

Update an existing app

Run this from the project folder:

uvx --from create-caspian-app casp update project          # latest
uvx --from create-caspian-app casp update project 0.0.1    # a specific version

Running create-caspian-app <name> inside a folder that has a caspian.config.json does the same. The update asks about any features that aren't enabled yet and re-pins the managed dependencies.

It replaces only the template files nobody changed. caspian.config.json keeps a scaffold ledger: the SHA-256 of every template file as the installer wrote it. Edit any file freely, by hand or with an AI agent; on the next update:

Take the template version of a file you edited with --force (repeatable):

uvx --from create-caspian-app casp update project -y --force src/app/index.py

Some files follow fixed rules instead: .env and uv.lock are never written, public/css/styles.css is rebuilt by the update's CSS build, src/app/globals.css only gains or loses the Tailwind directives, pyproject.toml only has the managed requirements re-pinned and missing uv run aliases added, and AGENTS.md only has its <!-- caspian:start --> block replaced, so your notes around it stay.

A project created before the ledger existed gets one on its first update: the installer re-runs the version recorded in its config into a temporary folder to learn exactly which files are unchanged.

Requirements

• Python 3.14+ for the installer and generated apps. uv can download Python 3.14 if it is missing.
• uv. If it's missing, the installer tries python -m pip install uv.