Get started
Quick start¶
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¶
- Tutorial: build an API layer by layer.
- 8. Projects and apps: add an app with its own models and migrations to this project.
- Notes example: a small CRUD API with a migration.