Plain
Documentation
Docs plain-start README.md

plain-start

Bootstrap a new Plain project from official starter templates.

Overview

You can create a new Plain project with a single command:

uvx plain-start my-project

This clones the official app starter template, configures your project name, initializes a fresh git repository, and runs the installation script. When it finishes, you'll have a working project ready to go.

cd my-project
uv run plain dev

Starter templates

Plain provides two official starter templates hosted on GitHub.

App starter (default)

The app starter includes everything you need for a full-featured web application:

  • Database ORM
  • User authentication
  • Admin interface
  • Session management
  • All core Plain packages
uvx plain-start my-app

Bare starter

The bare starter is a minimal setup for when you want to start from scratch:

  • Plain framework core only
  • Development tools
  • No database or auth
uvx plain-start my-project --type bare

Options

--type

Choose which starter template to use. Defaults to app.

uvx plain-start my-project --type bare

--no-install

Skip running the ./scripts/install script after cloning. Use this if you want to inspect the project before installing dependencies.

uvx plain-start my-project --no-install
cd my-project
# review the project structure...
./scripts/install

FAQs

What happens during project creation?

The cli command performs these steps:

  1. Clones the starter repository (shallow clone for speed)
  2. Removes the .git directory and initializes a fresh repository
  3. Updates the project name in pyproject.toml
  4. Runs ./scripts/install to set up dependencies (unless --no-install is used)

Where are the starter templates hosted?

The starter templates are hosted on GitHub:

  • App starter: https://github.com/dropseed/plain-starter-app
  • Bare starter: https://github.com/dropseed/plain-starter-bare

What if the directory already exists?

The command will exit with an error. You'll need to choose a different project name or remove the existing directory first.

What if the install script fails?

If the installation script fails, you'll see a warning message. You can try running ./scripts/install manually after investigating the issue.

Installation

The recommended way to use plain-start is with uvx, which runs the command without needing to install it first:

uvx plain-start my-project

If you prefer to install it globally:

uv tool install plain-start
plain-start my-project