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@latest my-app

Use @latest to check for the newest published installer. Without it, uvx can reuse a cached older version. Verify with uvx create-caspian-app@latest --version; use @0.0.7 instead to run that exact release.

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, the installer runs settings/build.py setup before the CSS build. Setup installs Tailwind's pinned official standalone executable and verifies its checksum. The shared user cache is reused by every project, so the same version/platform is downloaded once. Existing verified project-local downloads can seed that cache. PulsePoint and Tailwind Merge are bundled scaffold files.

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@latest my-app --tailwindcss --mcp --prisma --websocket -y
uvx create-caspian-app@latest my-app --prisma --websocket -y

Update an existing app

Run this from the project folder:

uvx --from create-caspian-app@latest casp update project          # latest
uvx --from create-caspian-app@latest 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@latest 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.