3.23 · Guides
Command line¶
The hinoki command accepts a module:attribute target for an application, factory, settings class or model module as documented by each subcommand. Targets are imported from the current project directory.
Targets such as notes.main:app, tracker.app:create_app and
blog.main:create_app refer to the checked-in project in examples/. Run
those commands from examples/; when using the repository checkout, prefix
them with uv run --project .. to use the locked environment at the parent.
Commands and options¶
| Command | Purpose |
|---|---|
hinoki new NAME |
Create a starter project with settings, rules, routes, tests and agent instructions. |
hinoki app list |
List registered apps, their model and migration modules, and dependencies without importing app code or opening a database. --format json is machine readable. |
hinoki app create NAME |
Add a registered modular app with its own models, routes and migration package. |
hinoki admin create-superuser NAME |
Create an admin user that holds every permission; the password is read without echo (or one line from stdin with --password-stdin). |
hinoki admin set-password NAME |
Change an admin user's password and end their sessions. |
hinoki app add NAME --models MODULE |
Register an existing package as an app in hinoki.toml without creating files. |
hinoki doctor [TARGET] |
Summarize environment, manifest and app construction diagnostics without serving or connecting to a database. |
hinoki dev TARGET |
Run an app with reload during development. |
hinoki serve TARGET |
Run without reload, using the server settings group. |
hinoki check TARGET |
Run the application's configured rules; --rules and --package select rule and source targets. |
hinoki routes TARGET |
List every method, path, handler and access policy in path order. --path and --method filter; --format json is machine readable. --lanes adds, per route, whether the Kiso runs it natively (native) or through the Python pipeline (python) with the reason; JSON always includes lane and lane_reason. Nothing is served and no database is opened. |
hinoki openapi TARGET |
Print or write the generated OpenAPI document, or check a JSON file for drift. Nothing is served and no database is opened. |
hinoki version |
Show the Hinoki version; --verbose includes Python, platform, native core and optional Granian details. --format json is machine readable. |
hinoki settings TARGET |
Show effective settings and their source, with secrets redacted. --dotenv and --toml select optional files. |
hinoki migrations ... |
Plan, inspect and apply project app migrations in dependency order. Legacy explicit targets remain available without a manifest. |
hinoki manage [TARGET] [COMMAND] |
Run an app-defined command with its declared module resources; a project manifest supplies the default target. |
hinoki shell [TARGET] |
Open an interactive Python shell with the app's modules and registered models. |
hinoki mcp TARGET |
Serve project context to an MCP client over stdio. Scenario tools are off by default. |
hinoki skills list / install |
List the optional agent skills, or write them under .claude/skills in the current project; see skills. |
hinoki completion SHELL |
Print a completion script for bash, zsh or fish; see Help and completion. |
On a colour terminal, doctor, check and routes print a coloured report: a status glyph per check (✔ ok, ▲ warning, ✘ failed or violated, – skipped) with the fix on its own line, and routes with coloured methods. When output is piped or redirected, or with NO_COLOR or TERM=dumb, the text is plain and unchanged, and --format json is never styled.
Help and completion¶
hinoki --help lists the commands in groups (Start, Inspect, Data, Integrate); hinoki COMMAND --help shows one command's options. A mistyped command or migrations action gets a suggestion:
hinoki: error: argument group: invalid choice: 'chek' (choose from ...)
did you mean 'check'?
The completion script is generated from the real parser, so it follows the commands and options of the installed version:
eval "$(hinoki completion bash)" # in ~/.bashrc
eval "$(hinoki completion zsh)" # in ~/.zshrc, after compinit
hinoki completion fish | source # in ~/.config/fish/config.fish
It completes command, subcommand and option names; it does not complete option values or project-specific names such as apps.
doctor¶
uv run hinoki doctor
uv run hinoki doctor notes.main:app --format json
With no target, doctor uses project.application from hinoki.toml. If there
is no manifest or default target, it reports environment checks and marks app
checks as skipped. An explicit TARGET can be an app or factory. Loading it
imports your Python code, so module-level code and the factory may have their
own side effects. Hinoki does not start app or module lifespans, run hooks,
start a server, run architecture rules, connect to a database, or write files.
The report covers manifest validity, Python/native extension and optional
Granian availability, route registration, configured typed settings, and
in-memory OpenAPI generation. An app with no settings object reports that
check as skipped; a custom non-Settings object is a warning. JSON output has
schema_version: 1 and stable check IDs. Settings values and exception
messages are not included. Exit status is 0 when no
diagnostic failed, 1 for invalid manifest or app diagnostics, and 2 when a
requested target cannot be loaded. Warnings and skipped checks remain visible.
Database connectivity and applied migration state are intentionally separate:
use hinoki migrations status for the live ledger and
hinoki migrations plan --check for
model-to-file drift.
new¶
hinoki new notes --dir . # or just `hinoki new` in a terminal for prompts
hinoki new notes --no-input --database sqlite --git --install
In a terminal, hinoki new with no NAME (or with some options missing) asks for what the flags left unset: name, parent directory, database, server, agent files, git init and uv sync. Pass --no-input (or run without a terminal, as in CI) to skip every prompt and use flags and defaults; NAME is then required.
| Option | Effect | Default |
|---|---|---|
--database none\|sqlite\|postgresql |
sqlite declares database: settings.DatabaseSettings in the project settings (local file under .hinoki/); postgresql also writes .env.example with a placeholder <NAME>_DATABASE__URL to copy to .env |
none |
--server kiso\|granian |
the server hinoki dev and hinoki serve run. kiso is Hinoki's own server, written in Rust (native handler lane, access log) and needs no configuration; granian is a general-purpose ASGI server and writes a settings.toml with [server] server = "granian", which the project settings read. <NAME>_SERVER__SERVER and --server on dev/serve still override it; see serving |
kiso |
--agent-files / --no-agent-files |
write or omit AGENTS.md, CLAUDE.md and .mcp.json |
written |
--skills / --no-skills |
also write the optional agent skills under .claude/skills (see skills); the terminal prompt asks for it |
off |
--git |
run git init in the project (no commit is made) |
off (prompt default: yes) |
--install |
run uv sync in the project |
off (prompt default: yes) |
On a colour, UTF-8 terminal (macOS and Linux) the prompts sit on a guide rail and answer to keys: type a name (backspace edits, Ctrl-U clears), move through the database and server lists with ↑/↓ or pick one by number, and switch yes/no with ←/→ or y/n; Enter confirms. Each answered prompt collapses into one summary line. The run then lists the key files it created, times git init and uv sync (with a spinner while they run) and ends with the next commands. Ghostty, kitty, iTerm2 and WezTerm show the Hinoki logo as an inline image; other terminals show a text wordmark. Elsewhere the prompts are numbered lists and [Y/n] questions answered with Enter.
Output that is piped, NO_COLOR and TERM=dumb give plain ASCII with no escape sequences. HINOKI_ANIMATE=0 (or CI) turns off the tagline animation and the spinner; HINOKI_IMAGES=0 (or running inside tmux/screen) uses the text wordmark. When the terminal reports a light background through COLORFGBG, darker shades of the same colours are used. Ctrl-C (or Esc in the key-driven prompts) or end of input cancels before anything is written (exit status 130).
git and uv run only when asked; a missing tool or a failing command prints a warning and does not undo the project. Nothing else is installed or run, and no database is created or contacted.
NAME is a lowercase package name containing letters and digits; it cannot be hinoki or a Python standard-library module name, because those names would shadow imports used by the generated project. --dir chooses the parent directory and defaults to the current directory. The target PATH/NAME must not exist or must be empty; nothing is overwritten.
This repository's pre-alpha Hinoki framework is not published on PyPI; the hinoki name belongs to an unrelated legacy package. The generated pyproject.toml therefore names this repository as the source under [tool.uv.sources]:
| Given | Source written |
|---|---|
--hinoki /path/to/checkout |
that checkout, editable |
--hinoki https://github.com/caspel26/hinoki@REV (or git+https://...) |
that repository, pinned to REV when given |
| nothing, running from a source checkout | the checkout you ran it from |
| nothing, any other installation | the public repository, default branch |
The result is cd PATH/NAME && uv sync && uv run pytest: the project has a health route, typed settings, rules, one test that needs no database, a README.md, AGENTS.md and .mcp.json.
Checkout paths and Git source values are escaped as TOML strings in the generated pyproject.toml.
app¶
The generated hinoki.toml registers the default app and its models and migrations. Add modules without moving files by creating another app:
uv run hinoki app create billing
This creates NAME/apps/billing/{models.py,routes.py,migrations/} and registers the model, migration and routes modules in hinoki.toml (routes = "NAME.apps.billing.routes:routes", prefix = "/billing"). Cross-app foreign keys require the referencing app to list the referenced app in requires in hinoki.toml; migrations are then planned/applied in dependency order. The project registry is explicit: Hinoki does not scan arbitrary installed packages or run imports at install time.
Both commands report hinoki.toml: hinoki new lists it among the generated files and app create says it registered the app there.
--prefix and --requires (comma-separated) set the mount prefix and dependencies directly. In a terminal, app create asks for whatever is not given — the name, the prefix (default /NAME) and, when other apps exist, requires — with the same prompts, Esc-to-cancel (exit 130, nothing created) and NO_COLOR handling as hinoki new. Without a terminal or with --no-input it never asks: the name is required (exit 2) and the defaults are /NAME and no requires.
To register a package that already exists, name its modules. Nothing is created or imported; only hinoki.toml changes:
uv run hinoki app add billing --models legacy.billing.models
uv run hinoki app add invoices \
--models legacy.invoices.models \
--migrations legacy.db.invoices \
--routes legacy.invoices.routes:routes --prefix /invoices \
--requires billing
--migrations defaults to the migrations package next to the models module (legacy.billing.migrations); a models module without a parent package needs it explicitly. --prefix defaults to /NAME once --routes is given. The whole manifest is validated before it is replaced, so a duplicate name, an unknown or cyclic --requires, or a malformed module name leaves hinoki.toml untouched and exits 2. Whether the modules import is checked later, when a command such as hinoki migrations plan loads the app.
List the registered apps from the project root or any subdirectory:
uv run hinoki app list
uv run hinoki app list --format json
The text output shows each app in dependency order with its model module, migration package, routes and prefix, and prerequisites. JSON contains the same fields under an apps key (routes and prefix are empty strings for an app without routes). The command only reads and validates hinoki.toml: it does not import app modules, connect to a database or start the app. Without a manifest, it prints an error and exits 2.
admin¶
The admin's own users are managed from the admin itself, except the first one:
uv run hinoki admin create-superuser ada # asks for the password twice, no echo
printf '%s\n' "$ADA_PASSWORD" | uv run hinoki admin set-password ada --password-stdin
A password is read from a terminal prompt or, with --password-stdin, from one line of standard input; it is never taken from the command line, where other users of the machine could read it, and it is never printed. Without a terminal and without the flag the command stops; with the flag on a terminal it still prompts without echo, and a line longer than a password can be is refused unread. Ctrl-C or Ctrl-D at the prompt exits with status 2, and a refused connection is reported as such (status 1), not as missing tables. The database is HINOKI_DATABASE_URL, --database, or the project's local SQLite, as for hinoki migrations. The user tables must exist: register and apply them first (hinoki app add admin ..., hinoki migrations apply admin, see who may sign in); otherwise the command exits 1 and says so. Usernames are lower-cased; the shortest password is admin.min_password_length. Exit status is 0 on success, 2 for a refused input (a taken name, a weak or mistyped password, an unknown user).
dev and serve¶
hinoki dev notes.main:app --host 127.0.0.1 --port 8000
hinoki serve notes.main:app --workers 4
hinoki serve notes.main:app --server granian --workers 2
Both commands accept --host and --port; they override settings.server.host and .port. serve also accepts --workers, overriding .workers. Both accept --server granian|kiso, overriding .server (default kiso). Otherwise values come from the app's settings.AppSettings.server group. dev enables reload and runs one worker. Granian (--server granian) and the watchfiles that dev reloads with come from the optional server extra.
--server kiso runs the application on Kiso, Hinoki's Rust HTTP server (see Running an application for what it does and does not do). A setting that the chosen server cannot honour (max_connections, header_read_timeout or body_read_timeout with granian) makes the command print error: server.<name> is not supported by the <server> server and exit with status 2. A build whose native extension has no Kiso exits 2 with a message instead of falling back to Granian. With several workers the command runs a supervisor that starts one process per worker; SIGTERM or Ctrl-C stops them gracefully, and a worker that dies stops the rest and makes the command exit non-zero.
check¶
hinoki check tracker.app:create_app \
--package tracker --phase startup --format text
Options:
--rules MODULE:ATTRIBUTEselects aRuleSet; the app's rules are used by default.--package PACKAGEselects a package for static import checks. Repeat it for multiple packages. Without it, the package containing the target is scanned.--phase startup|staticselects a phase; the default runs both.--waivers PATHselects a waiver file; the default ishinoki-rules.tomlin the current directory.--format text|jsonselects human-readable or versioned JSON output.--allow-effectsalso runs checks declared as effectful, which may access files, network or databases.
Exit status is 0 when no rules fail, 1 for violations, and 2 when the target or checks cannot run.
openapi¶
hinoki openapi notes.main:app
hinoki openapi notes.main:app --output openapi.json
hinoki openapi notes.main:app --check openapi.json
The command builds the app without serving it or opening a database; it works even when openapi_url is disabled. With no file option it prints deterministic JSON (sorted keys, two-space indentation and a trailing newline). --output FILE writes those bytes. --check FILE compares parsed JSON, so formatting differences do not count as drift. Exit status is 0 when the file matches or is written, 1 when its JSON differs, and 2 when the target cannot load or the check file is missing or invalid JSON. --output and --check cannot be used together.
--breaking-against BASELINE compares the generated document with an earlier OpenAPI JSON file (the released version) and prints one breaking: … line per change that would break an existing client:
hinoki openapi notes.main:app --output openapi-baseline.json # at release time
hinoki openapi notes.main:app --breaking-against openapi-baseline.json
Reported: a removed operation or success response, new or newly required request input, a removed response property, a changed type, and a request enum that narrows or a response enum that widens. Additions are compatible and are not reported. Exit status is 0 when nothing breaks, 1 when something does, and 2 when the target cannot load or the baseline is missing or not a JSON object. It cannot be combined with --output or --check. The comparison reads the documents only; it does not check behavior that an OpenAPI document does not describe.
version¶
hinoki version
hinoki version --verbose
hinoki version --verbose --format json
The default prints hinoki X.Y.Z. --verbose adds the Python version, platform, native extension path and Granian version; Granian is reported as not installed when its optional package is absent. Use --format json for machine-readable output. Details the binding does not expose, including its bundled SQLite library version, are omitted rather than inferred.
settings¶
hinoki settings blog.settings:BlogSettings \
--prefix BLOG_ --dotenv .env --toml settings.toml --format json
hinoki settings blog.settings:BlogSettings --example > .env.example
TARGET can be a settings class or an app with typed settings. --prefix, --dotenv and --toml override sources declared by the settings class. --format text|json selects output; --example prints a .env.example with defaults and types, leaving secrets and required fields blank. Values of settings.Secret are redacted.
manage¶
hinoki manage --help
hinoki manage greet Peppe
Commands are declared on the app with Hinoki(commands=[...]). Each command subclasses hinoki.management.Command, gives itself a lower-case name, and adds arguments through add_arguments(parser). In a scaffolded project, hinoki manage lists commands and hinoki manage greet Peppe runs one; the manifest's project.application supplies the app target. Outside a registered project, use hinoki manage TARGET COMMAND. --help after a command shows its arguments.
from argparse import ArgumentParser, Namespace
from hinoki import Hinoki
from hinoki.management import Command, CommandContext
class Greet(Command):
name = "greet"
help = "print a greeting"
def add_arguments(self, parser: ArgumentParser) -> None:
parser.add_argument("name", nargs="?", default="world")
def handle(self, _context: CommandContext, args: Namespace) -> None:
print(f"Hello, {args.name}!")
app = Hinoki(commands=[Greet])
The same example is in examples/project/app.py; the examples manifest supplies
its target when you run the command from the examples/ project directory.
handle(context, args) may be synchronous or asynchronous. A sync handler runs on Hinoki's bounded executor. It can read context.settings and retrieve resources with context.get(Type) or context.find(Type). Declare module classes in the command's requires tuple; Hinoki starts those modules and their dependencies for the command, then closes them before it exits. Other app modules are not started. A command with no requirements starts no app modules.
Commands run inside the project process and can modify data. Use disposable databases when developing or testing a command that writes. A handler returns None for success or an exit code from 0 through 255. Unknown commands and invalid arguments exit 2; a command failure exits nonzero. App settings load when Hinoki constructs the app, but module resources open only for the selected command.
shell¶
uv run hinoki shell
uv run hinoki shell blog.main:app --models blog.models
In a project with hinoki.toml, the target defaults to project.application
and the shell loads every registered app's model module. Repeat --models
to select model modules explicitly. Outside a project, pass a target; --models
is optional. The interactive namespace contains app, its validated
settings, and concrete model classes. Conflicting model class names fail
before the prompt.
The shell keeps one event loop and supports top-level await:
>>> await Note.all()
[Note(id=1, title='Hello')]
>>> app.title
'Hinoki Blog'
Use async ORM queries with await; synchronous ORM methods cannot block the
shell's event loop. Unmanaged tasks are cancelled on exit and cleanup is
bounded by app.runtime.shutdown_timeout.
Installed module resources are started and closed for the session, so ORM
queries use the app's configured database. App on_startup and on_shutdown
hooks do not run, and migrations are never applied. The shell requires a TTY;
Ctrl-D exits, Ctrl-C at the prompt exits, and Ctrl-C during a cell interrupts
that cell. It executes Python with the current user's process privileges and
may write to the configured database, so use a development database when
experimenting.
On a colour terminal the shell opens with the Hinoki banner (the logo as an inline image where the terminal supports it), a summary of the app title, its settings class and the loaded models, and a hinoki ❯ prompt. NO_COLOR, TERM=dumb, HINOKI_ANIMATE=0 and HINOKI_IMAGES=0 behave as for hinoki new; without colour the shell prints the plain greeting and Python's >>> / ... prompts.
migrations¶
In a project created by hinoki new, migration modules are read from the manifest; users do not supply model or migration paths:
uv run hinoki migrations plan --name add-index --dry-run
uv run hinoki migrations plan --check
uv run hinoki migrations plan --app billing --name add-invoice-index
uv run hinoki migrations status
uv run hinoki migrations apply
uv run hinoki migrations sql --app billing 0001-initial
status and apply cover all registered apps in dependency order. Writing a
plan in a multi-app project requires --app; read-only plan --check and
plan --dry-run without --app cover every app in dependency order. sql
likewise requires an app in a multi-app project. --name is optional for a
focused plan: Hinoki derives a stable slug from the first planned schema change
(for example, create-table-notes); pass --name initial-notes to override
it. All-app previews cannot use --name. Numbering is automatic. apply
initializes the configured local SQLite database when no database URL is set.
In a manifest project the implicit .hinoki/local.sqlite3 file is rooted
beside hinoki.toml, even if you run the command from a subdirectory; explicit
relative SQLite URLs remain relative to the current working directory. Added
apps have separate migration ledger namespaces, so identical numbered
filenames do not collide; the scaffolded root app retains its existing
unprefixed migration keys. --app billing includes its declared prerequisite
apps for migration application.
Use plan --check in CI to fail when model changes are missing from committed
migration files. It exits 1 when operations are pending and 0 when the
files match the models. It is read-only: it imports registered model modules
and the selected migration package but does not write migration files or
connect to a database. Project planning loads every registered app's models
to validate cross-app foreign keys, even when --app selects one migration
package. Without --app, it checks every app in dependency order; --app NAME
limits the check to that app and its prerequisites. Destructive operations
are reported as pending too. This checks model-to-file drift only;
migrations status checks which migration files have been applied to a live
database. plan --dry-run without --app previews every app and exits
successfully when it prints planned operations. The all-app preview is
hypothetical and writes no files; a dependent plan shown there may need its
prerequisite migration generated and reviewed first. Ordinary app-local
destructive changes are previewed without requiring --allow-destructive.
Before writing a focused plan, Hinoki verifies that cross-app foreign-key
targets exist in the prerequisite app's recorded migration state and have a
compatible primary-key column. It also refuses parent teardowns while any
recorded state of another app still refers to the target, including for
--dry-run and --check and even with --allow-destructive. An all-app
preview fails without partial diffs in this case. Remove and apply the child
foreign key in a separate deployment phase before preparing the parent teardown. See
migrations for the limits of this
file-based check.
Without a hinoki.toml, the explicit legacy form remains:
hinoki migrations --dir myapp/migrations plan \
--models myapp.models --name add-index --dry-run
hinoki migrations --dir myapp/migrations plan \
--models myapp.models --name add-index --allow-destructive
export HINOKI_DATABASE_URL="$APP_DATABASE__URL"
hinoki migrations --dir myapp/migrations status
hinoki migrations --dir myapp/migrations apply
hinoki migrations --dir myapp/migrations sql 0001-initial
plan requires --models MODULE; --name is an optional slug override and is derived from the first planned schema change when omitted. --dry-run prints operations without writing files. Destructive operations require --allow-destructive. Without HINOKI_DATABASE_URL, plan/status/apply target the local SQLite file at .hinoki/local.sqlite3; --database URL selects another supported backend. A URL given as an argument is visible in the process list and shell history, so keep a URL containing a password in the environment. When the connection fails, the command prints error: database: … with a fix: line and exits 1; the URL is not printed. sql NAME prints a migration's SQL. Use a disposable database while reviewing migrations.
On an animated terminal, plan and apply show a spinner while they work and finish with a timing line (✔ applied 1.2s); the commands' own output is printed unchanged before it. Piped output, NO_COLOR, TERM=dumb, CI and HINOKI_ANIMATE=0 print only the commands' own output.
mcp¶
hinoki mcp tracker.app:create_app \
--rules tracker.rules:tracker_rules \
--package tracker --models tracker.models
The development server uses MCP over stdio. It accepts --rules, repeatable --package, repeatable --models, and --waivers with the same target meanings as check. --requests PATH names the file the recent_requests tool reads (default .hinoki/requests.jsonl; see server.recent_requests). --scenarios off|read|write controls whether run_scenario is registered: read allows GET, HEAD, OPTIONS and QUERY; write allows every supported method. Scenarios start the real app, run handlers and lifespan hooks, and may write data even for a GET. Keep the tool server owner-controlled and point the app at a disposable database.
The development MCP is separate from application MCP, which is mounted with expose_as_mcp and an explicit action allowlist. See the development MCP guide for tool inputs and results.
skills¶
hinoki skills list
hinoki skills install # from a project directory
hinoki skills install --force # replace skills that already exist
Agent skills are short Markdown playbooks that point an assistant at the real Hinoki tools (the development MCP and the CLI). list prints each skill name and description. install reads hinoki.toml, then writes .claude/skills/<skill>/SKILL.md for each one, with the project package name filled in; an existing file is kept and reported unless --force replaces it. Without a manifest it prints an error and exits 2. hinoki new --skills writes the same files at creation. They are optional and never written otherwise.
| Skill | Playbook |
|---|---|
hinoki-add-endpoint |
add an action with its Schema types, access policy and test |
hinoki-fix-rule |
fix a rule diagnostic without editing the rules or waivers |
hinoki-review-api |
run hinoki openapi --breaking-against before and after a change |
hinoki-test-api |
exercise operations with the generated valid and invalid bodies of hinoki.ai.samples.request_cases |
Import target examples¶
hinoki dev notes.main:app
hinoki check tracker.app:create_app
hinoki settings blog.settings:BlogSettings
hinoki migrations plan --app blog --name add-index --dry-run
When a target import fails, check that the command runs from the project directory, the package has __init__.py files where needed, and the attribute name is correct.