pre-alpha

Get started

Quick start

implemented Updated November 20, 2026 3 min read

Create a project, run its tests and serve it. Everything runs locally; the database is a SQLite file.

Create a project

From the Hinoki checkout:

uv run hinoki new

hinoki new asks only what it needs. Give these answers and keep the other defaults:

Prompt Default Answer
Project name notes
Parent directory . .. (beside the checkout)
Database none sqlite
Server kiso kiso
Agent instructions and MCP config? yes yes
Agent skills? no no
Initialize a git repository? yes yes
Install dependencies (uv sync)? yes yes

It writes the project, runs git init and uv sync, and prints the next commands. The files that matter:

notes/
├── hinoki.toml        manifest: application, routes, apps
├── notes/
│   ├── main.py        the application
│   ├── api.py         GET /health
│   ├── routes.py      routes = [health]
│   ├── settings.py    typed settings, NOTES_* variables
│   └── rules.py       architecture rules
├── tests/             pytest suite
└── AGENTS.md          agent instructions

Scripts and CI

uv run hinoki new notes --dir .. --no-input --database sqlite --git --install gives the same answers without prompts. Plain --no-input uses the defaults instead: no database, no git init, no uv sync. All options are in hinoki new.

Test and serve it

cd ../notes
uv run pytest
uv run hinoki dev

The test calls /health in process and needs no database. hinoki dev serves on http://127.0.0.1:8000 and reloads when a file changes. In another terminal:

curl http://127.0.0.1:8000/health
{"status":"ok"}

At startup hinoki dev logs a warning that allowed_hosts is '*': the application answers to any Host header. It is harmless on your machine. To name the hosts you serve, and silence it, add NOTES_ALLOWED_HOSTS=127.0.0.1,localhost to .env; see allowed_hosts.

Open http://127.0.0.1:8000/docs for the generated OpenAPI UI, or run uv run hinoki routes to list every route with its access policy.

What the manifest does

hinoki.toml names the application and where its routes, models and migrations live:

[project]
application = "notes.main:app"
routes = "notes.routes:routes"

[[apps]]
name = "notes"
models = "notes.models"
migrations = "notes.migrations"
requires = []

notes/main.py declares the application:

# notes/main.py
from hinoki import Hinoki
from hinoki.project import manifest_routes

from notes.rules import project_rules
from notes.settings import ProjectSettings

app = Hinoki(
    settings=ProjectSettings,  # NOTES_* variables and .env
    include=manifest_routes(),  # notes/routes.py, then each app's routes at its prefix
    title="Notes",
    openapi_url="/openapi.json",
    docs_url="/docs",
    rules=project_rules,
)

manifest_routes() reads hinoki.toml, so the application lists no routes of its own. Commands read the same file, so inside the project they need no module paths.

Where the database is configured

Answering sqlite added one field to notes/settings.py:

# notes/settings.py
from hinoki import settings


class ProjectSettings(settings.AppSettings, prefix="NOTES_", dotenv=".env"):
    database: settings.DatabaseSettings

With no value set, it is the SQLite file .hinoki/local.sqlite3. Each field of DatabaseSettings is a NOTES_DATABASE__<FIELD> variable (two underscores between the group and the field), read from the environment or from .env in the project directory. uv run hinoki settings lists every variable and where its value came from. To use another file:

# .env
NOTES_DATABASE__URL=sqlite://./.hinoki/notes.sqlite3

Configure a database covers PostgreSQL, MySQL and MariaDB, and connection fields instead of a URL. The project has no models yet; the tutorial and 8. Projects and apps add them.

Next