Available commands

Command	What it does
`init`	Start a new PyBlade project
`dev`	Run the development server
`make:template`	Create a template
`make:component`	Create a component
`make:live`	Create a live component
`make:command`	Create your own command
`copy:stubs`	Copy PyBlade's own templates into your project to customize them
`messages:make`	Extract translatable strings
`messages:compile`	Compile translations
`tailwind:config`	Install and configure Tailwind CSS
`upgrade`	Upgrade PyBlade
`docs`	Open this documentation

`pyblade init`

Starts a new PyBlade-powered project: it creates the project with your framework's own tooling, installs its dependencies with a package manager, connects PyBlade to it, writes a pyblade.toml, and gives you a layout and a welcome page.

pyblade init [OPTIONS]

The command asks you:

Project name. Use . to start the project in the current directory. The default is my_project.
Framework. Django, Flask or FastAPI.
Tailwind CSS. Whether to install and configure it.

It then shows a summary and asks you to confirm before writing anything. It refuses to start in a directory that already holds a project (a manage.py or a pyblade.toml), so it can never write over your work.

Options

Option	Description
`--package-manager`	What the new project manages its dependencies with: `uv`, `poetry`, `pipenv` or `pip`. By default, the best one found on your machine.

pyblade init --package-manager uv

`pyblade dev`

Starts the development server and, in a project that uses Tailwind CSS, builds your stylesheet and rebuilds it as you edit your templates.

pyblade dev [ADDRPORT] [OPTIONS]

In a Django project, this is Django's development server. For Flask and FastAPI, PyBlade starts the framework's server with the tool your project manages its dependencies with, so the right environment is used even if it isn't activated.

The development server is not meant for production.

Arguments

Argument	Description
`addrport`	Optional `host:port` to listen on. Default: `127.0.0.1:8000`.

Options

Option	Description
`-h`, `--host`	The host to bind to.
`-p`, `--port`	The port to bind to.
`--no-css`	Don't build the Tailwind stylesheet while the server runs.
`--no-reload`	Disable auto-reload.

The other options (--settings, --ipv6, --insecure, --nostatic, --nothreading, --skip-checks, --traceback, --verbosity, --no-color, --force-color, --pythonpath) are Django's, passed on to runserver. See pyblade dev --help.

pyblade dev --host 0.0.0.0 --port 5000

Aliases

pyblade serve

`pyblade make:template`

Creates a new template in your templates folder (paths.templates).

pyblade make:template NAME [OPTIONS]

Argument / option	Description
`NAME`	The name of the template, without the extension. Separate folders with dots: `blog.post` creates `templates/blog/post.html`.
`-a`, `--app`	In a Django project, create the template in the `templates` folder of this app instead. See Creating files in a Django app.
`-f`, `--force`	Overwrite the template if it already exists.

pyblade make:template home

This creates templates/home.html.

`pyblade make:component`

Creates a new component: a reusable piece of template. The file goes in your components folder (paths.components).

pyblade make:component NAME [OPTIONS]

Argument / option	Description
`NAME`	The name of the component. Separate folders with dots: `ui.alert` creates `components/ui/alert.html`. A name in PascalCase (`AlertBox`) is turned into `alert_box`.
`-a`, `--app`	In a Django project, create the component in the `components` folder of this app instead. See Creating files in a Django app.
`-l`, `--live`	Create a live component instead: a Python class and its template.
`-i`, `--inline`	Create a live component without a template file, the template being written inside its class. This must be used with the `--live` oprtion.
`-f`, `--force`	Overwrite the component if it already exists.

pyblade make:component alert
pyblade make:component ui.card

Without --force, the command refuses to write over a component that already exists.

Where files are created

make:template, make:component and make:live create files where your project says templates and components are (paths.templates and paths.components), from the root of the project, wherever you run the command. Run from a subfolder, the file still lands in the project's own templates/ or components/, never in a new folder next to you.

Creating files in a Django app

A Django project is often made of apps, and an app can bring its own templates and components, the way it brings its own models. Give the app's label with --app and the file is created in that app instead of at the root of the project:

pyblade make:template billing.invoice --app billing
pyblade make:component ui.badge --app billing
pyblade make:live cart --app billing

apps/billing/templates/billing/invoice.html
apps/billing/components/ui/badge.html
apps/billing/components/cart/cart.py
apps/billing/components/cart/cart.html

The folder names are the ones your project uses (templates and components by default), created inside the app. If the label is not one of your project's apps, the command lists the labels that are. --app only makes sense in Django projects.

Templates of an app are found the way Django finds them. For components, see how components are found.

`pyblade make:live`

Creates a new live component: a Python class and its template.

pyblade make:live NAME [OPTIONS]

Argument / option	Description
`NAME`	The name of the component, with dots for folders, as in `make:component`.
`-a`, `--app`	In a Django project, create the component in the `components` folder of this app instead. See Creating files in a Django app.
`--flat`	Create the two files side by side, without a folder.
`-i`, `--inline`	Write only the Python class, with the template inside it, instead of a separate `.html` file.
`-f`, `--force`	Overwrite the component if it already exists.

pyblade make:live counter

This creates two files in your components folder:

components/counter/counter.py     # the Counter class
components/counter/counter.html   # its template

With live_components.flat set to true, the two files are created side by side, without the counter/ folder.

Aliases

pyblade make:livecomponent

`pyblade make:command`

Creates a command of your own, from a ready-to-fill skeleton.

pyblade make:command NAME [OPTIONS]

Argument / option	Description
`NAME`	The name of the command file, also used as the name of the command: `report:send` creates `report:send.py`, in the commands folder of your project (`paths.commands`).
`-d`, `--description`	The description shown in the command's help.
`-f`, `--force`	Overwrite the command if it already exists.

Read Custom commands to see how to fill it in.

`pyblade copy:stubs`

PyBlade draws some parts of a live application itself, such as the pagination links. copy:stubs copies those templates into your project, so you can change them. Once a copy exists, PyBlade draws with yours instead of its own.

pyblade copy:stubs --pagination [--force]

Option	Description
`--pagination`	Export the pagination templates, to `templates/stubs/pagination/`.
`-f`, `--force`	Overwrite templates that were already exported.

You must say what to export. For now, that is --pagination.

`pyblade messages:make`

Goes through your project, finds every string marked for translation (@trans, @blocktrans), and creates or updates the .po translation files, one per language, in your locale folder (i18n.directory).

pyblade messages:make [OPTIONS]

You must give one of --locale, --all or --exclude.

Option	Description
`-l`, `--locale`	The locale to create messages for (`fr`, `de`, `es`...).
`-a`, `--all`	Create messages for every locale already found in the locale folder.
`-x`, `--exclude`	Comma-separated locales to skip: `fr,de`.
`-d`, `--domain`	The gettext domain. Default: `django` in a Django project, `pyblade` otherwise.
`-e`, `--extensions`	Comma-separated file extensions to read. Default: `html,py`.
`-i`, `--ignore`	Comma-separated files or folders to ignore.

pyblade messages:make --locale fr
pyblade messages:make --all

Aliases

pyblade make:messages

`pyblade messages:compile`

Compiles the .po files into .mo files, the form the translations are read in. Run it after every change to a translation.

pyblade messages:compile [OPTIONS]

Option	Description
`-l`, `--locale`	The locale to compile. By default, all of them.
`-x`, `--exclude`	Comma-separated locales to skip.
`-d`, `--domain`	The gettext domain. Default: `django` in a Django project, `pyblade` otherwise.
`-i`, `--ignore`	Comma-separated directories to ignore.
`-f`, `--fuzzy`	Compile fuzzy translations as well.

If the command can't find your locale folder, create it or set i18n.directory in pyblade.toml.

Aliases

pyblade compile:messages

`pyblade tailwind:config`

Installs Tailwind CSS in the project and configures it to read your templates and build a stylesheet. Afterwards, pyblade dev builds the stylesheet as you work.

pyblade tailwind:config [--no-install]

Option	Description
`--no-install`	Configure the project without installing anything.

The command needs a JavaScript package manager (npm, pnpm, yarn or bun), detected from your project or set with stack.js_package_manager. It records the result in pyblade.toml.

Aliases

pyblade tw:config

`pyblade upgrade`

Upgrades PyBlade to the latest version, with your project's package manager.

pyblade upgrade

`pyblade docs`

Opens this documentation in your default browser.

pyblade docs

Available commands

On this page