CLI

Create

This is the chapter the whole guide has been quietly building toward. Every structure we assembled by hand — the config, the routers, the models, the services, the frontend workspace — is what a single wf create project lays on the table in one go. Let's meet it.

wf create project

One command scaffolds a complete, opinionated project and walks you through the frontend choice interactively:

terminal bash 
wf create project myapp

And out comes the shape we've been converging on all along:

myapp/ text 
myapp/
├── main.py                 # app factory, includes the routers
├── .gitignore
├── additives/              # your Additives live here
└── fluid/
    ├── config.py           # register_config Config (APP_CONFIG, APP_FRONTEND)
    ├── api/
    │   ├── __init__.py      # api_router (prefix /api)
    │   └── v1/
    │       ├── __init__.py  # v1 router (prefix /v1)
    │       └── health.py    # the /api/v1/health endpoint
    ├── app/                 # HTML routes (index.py) — for htmx / none
    ├── frontend/            # Vite workspace — for the vite type
    ├── models/              # SQLAlchemy models
    ├── schemas/             # pydantic schemas
    ├── services/            # business logic
    ├── events/              # event + query handlers
    ├── utils/               # your helpers
    ├── static/
    │   ├── css/tailwind_raw.css
    │   ├── img/
    │   └── js/
    └── templates/
        └── index.html       # extends fluid_base.html

If that layout looks familiar, it should — you've built every part of it across the last chapters:

  • main.py is the app factory we adopted back in the Migrate chapter.
  • fluid/config.py is the config class with APP_CONFIG and APP_FRONTEND.
  • fluid/api and fluid/app are the JSON and HTML routers, split out cleanly.
  • fluid/models, schemas, services, events, utils are the homes we kept reaching for as the app grew.
  • fluid/frontend and the Tailwind entry point are the surface we wired up by hand.
 

The frontend type you pick decides two details: choose vite and you get the fluid/frontend workspace (the app/ folder is dropped, since the Vite index owns /); choose htmx or none and you get the app/index.py HTML route with a ready index.html instead. Useful flags: --skip-defaults, --skip-frontend and --babel-fallback.

wf create app

A project can serve many apps, and each app is just a config. wf create app builds one interactively — it generates a secret, asks for your database and redis uris, and lets you tick the extensions, features and Additives to enable. It even pulls in any questions your Additives contribute through their configure setup:

terminal bash 
wf create app prod

The result is a fully populated app_configs/prod.ini — the same kind of file we hand-wrote in Getting Started, only now filled in for you with a real secret key and every switch in place.

wf create additive

And the third scaffolder closes the loop on the Additives chapters. wf create additive asks for an id, a version format, whether it's a base or should extend one, its frontend, and which extensions it requires — then writes the whole package, manifest and all:

terminal bash 
wf create additive portal
 

That's the payoff of the red thread: the framework's conventions aren't a cage, they're a destination. You can build every piece by hand — and now that you understand each one, you can let the CLI lay them down for you and get straight to the interesting part.

Continue reading

From here you can continue straight with Run.