Installation

Get Chirp installed, add optional extras when you need them, and scaffold a running project. Chirp ships routing, templates (Kida), return-type content negotiation, middleware, forms, validation, sessions, auth helpers, streaming HTML, SSE, static files, testing tools, and hypermedia contract checks in one framework. Optional PyPI extras add multipart parsing, argon2, chirp-ui, PostgreSQL access, LLM streaming, and Redis — see the table below.

Prerequisites

Python 3.14+ (free-threading build recommended)

Install

uv add bengal-chirp

pip install bengal-chirp

git clone https://github.com/lbliii/chirp.git
cd chirp
uv sync --group dev

Verify

import chirp
print(chirp.__version__)

You should see the installed version printed. Now scaffold your first project:

chirp new myapp
cd myapp
python app.py

Open http://127.0.0.1:8000in your browser.

Optional extras

Most new apps start withchirp new, which expects forms, sessions, and often [ui]. The table below lists PyPI extras you add when a feature is not already pulled in by your scaffold or deployment image:

Extra	Provides	Install
`forms`	Multipart form parsing (file uploads)	`uv add "bengal-chirp[forms]"`
`sessions`	Signed cookie sessions (hardening guide)	`uv add "bengal-chirp[sessions]"`
`auth`	Argon2 password hashing	`uv add "bengal-chirp[auth]"`
`testing`	The test client (httpx transport)	`uv add "bengal-chirp[testing]"`

# Common starting set for a full-stack app
uv add "bengal-chirp[forms,sessions,testing]"

Extra	Provides	Pulls in
`forms`	Multipart form parsing (file uploads)	`python-multipart`
`sessions`	Signed cookie sessions	`itsdangerous`
`auth`	Argon2 password hashing	`argon2-cffi`
`testing`	Test client transport	`httpx`
`data-pg`	PostgreSQL access	In-tree pure-Python pelt driver (no extra dependency)
`ai`	LLM streaming over raw HTTP	`httpx`
`markdown`	Markdown rendering with syntax highlighting	`patitas[syntax]`
`ui`	chirp-ui component library	`chirp-ui`
`config`	Load config from a local`.env`file	`python-dotenv`
`redis`	Redis-backed sessions and rate limiting	`redis`
`all`	The common extras together	`forms` + `sessions` + `auth` + `testing`/`ai` + `data-pg` + `markdown`

SQLite needs no extra — it ships in the standard library assqlite3. The all extra covers the broadly useful set; it does not includeui, config, or redis, which you add deliberately. Install several at once with a comma list: uv add "bengal-chirp[forms,auth,data-pg]".

CLI commands

After installation thechirpcommand is available:

Command	Description
`chirp new <name>`	Scaffold an auth-ready project with filesystem pages, static assets, and tests
`chirp new <name> --minimal`	Scaffold a minimal single-file project
`chirp new <name> --shell`	Scaffold with a persistent app shell (topbar + sidebar)
`chirp new <name> --sse`	Scaffold with SSE boilerplate (`EventStream`, `sse_scope`)
`chirp new <name> --with-chirpui`	Require ChirpUI templates (fail if`chirp-ui`is not installed)
`chirp dev <app>`	Development server with browser reload on template/CSS changes
`chirp run <app>`	Start the server (e.g.`chirp run myapp:app`)
`chirp check <app>`	Validate hypermedia contracts from the command line
`chirp check <app> --warnings-as-errors`	Exit non-zero on contract warnings (CI gate)
`chirp check <app> --coverage`	Show route/template contract coverage counters
`chirp check <app> --deploy`	Run checks at production severity (implies`--warnings-as-errors`)
`chirp routes <app>`	Print the registered route table
`chirp freeze <app> <output>`	Render routes to static HTML files
`chirp security-check <app>`	Audit app config against the security checklist
`chirp makemigrations --db <url> --schema <module>`	Generate a schema migration from model changes
`chirp migrate --db <url> --migrations-dir <dir>`	Apply pending schema migrations (one-shot deploy job)

See the CLI reference for full flag details.

Installation

Prerequisites

Install

Verify

Optional extras

CLI commands

Next steps