After Creating

sillo-start has finished. Everything from here is the sillo command, which the project has as soon as its dependencies are installed.

Install

uv (recommended)

cd myapp
uv sync

Reads pyproject.toml and uv.lock, creates .venv, and installs exactly the locked versions. Add --all-extras to include the dev tools (pytest, ruff, httpx) which is what you want in a project you are working on:

uv sync --all-extras

venv + pip

cd myapp
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

-e installs the project itself in editable mode, so app and routes are importable without reinstalling after every change. [dev] adds the test and lint tools.

Everything below assumes the environment is active. With uv, prefix each command with uv run instead, uv run sillo db:migrate.

Set the database up

sillo db:migrate

The starter commits its initial migration, so this produces a working schema rather than an empty database. SQLite by default, at storage/myapp.db.

Check it worked:

sillo db:status

Create an administrator

sillo user:admin you@example.com

Prompts for a password, twice, without echoing. This is the account you sign in to /admin/ with.

Run it

uvicorn app:app --reload

Then open http://localhost:8000, and the admin panel at http://localhost:8000/admin/.

--reload restarts on source changes. It is for development only. See Deployment for the production shape.

Run the tests

pytest

The starter ships a working suite with fixtures for an authenticated client. It is worth running once before you change anything, so you know the baseline is green on your machine and not only in CI.

See what this project can do

sillo

Lists every command, including the ones your application’s own setup brought in. That listing is derived from the application. A project with a scheduler shows the schedule:* commands, one without does not.

sillo routes

Every route the application registers, with its methods and name. The quickest way to get oriented in a codebase you have just met.

Then

• Read app/bootstrap.py. It is where the application is assembled, and it is the shortest path to understanding what is switched on.
• Look at database/models/user.py. Your models go beside it.
• Add a route in routes/web.py or routes/api.py.

Project structure walks the layout in detail, and Configuration covers .env and app/config.py.

Common first problems

sillo: command not found. The environment is not active, or dependencies are not installed. With uv, use uv run sillo or activate .venv.

No application found. You are not in the project directory. sillo looks for the application relative to the working directory. See Finding your application.

Migrations do nothing. Check DATABASE_URL in .env points where you think. sillo db:status prints what it is working against.

The admin panel 404s, ADMIN_ENABLED in .env, and the account needs admin access. sillo user:staff you@example.com grants it.