GuidesRuntime
Inspect an application¶
These commands load the application, report and exit. None of them serves
requests, opens a database or writes files (except openapi --output):
uv run hinoki doctor
uv run hinoki routes
Each accepts --format json for scripts. On a colour terminal the reports use
✔ ok, ▲ warning, ✘ failed and – skipped; piped output, NO_COLOR and
TERM=dumb give plain text.
Diagnose a project with doctor¶
uv run hinoki doctor
uv run hinoki doctor --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 names another app (module:app).
Loading it imports your Python code, so module-level code may have its
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.
Check the rules with check¶
uv run hinoki check
uv run hinoki check --phase static
| Option | Effect | Default |
|---|---|---|
--rules MODULE:ATTRIBUTE |
the RuleSet to run |
the application's rules= |
--package PACKAGE |
package for the static import checks; repeat for several | the package that contains the target |
--phase startup\|static |
run one phase | both |
--waivers PATH |
waiver file; must exist | the app's waivers=, else hinoki-rules.toml at the project root (which file) |
--format text\|json |
human or versioned JSON output | text |
--allow-effects |
also run checks declared effectful (files, network, database) | off |
Exit status is 0 when no rule fails, 1 for violations and 2 when the target
or the checks cannot run. What each rule checks, and how to read and waive a
result, is in Rules.
List routes with routes¶
uv run hinoki routes
GET /billing/invoices StaffTokens[billing:manage] notes.apps.billing.api.list_invoices
POST /billing/invoices StaffTokens[billing:manage] notes.apps.billing.api.create_invoice
GET /billing/invoices/{invoice_id} StaffTokens[billing:manage] notes.apps.billing.api.get_invoice
GET /health public notes.api.health
Each row is method, path, access (the provider and its permissions, or public)
and handler, sorted by path. The handler is the action's rule subject, the name
that except_ and waivers match: an action of an API class is named after the
class it is mounted on, even when it inherits the method. --path keeps paths
that start with the prefix, --method one method; no match prints
no routes match and exits 1:
uv run hinoki routes --path /billing --method GET
GET /billing/invoices StaffTokens[billing:manage] notes.apps.billing.api.list_invoices
GET /billing/invoices/{invoice_id} StaffTokens[billing:manage] notes.apps.billing.api.get_invoice
--lanes adds, per route, whether Kiso runs
the handler natively (native) or through the Python pipeline (python), with
the reason. The access log's lane field means something narrower: a request
for a native route here still logs python unless Rust runs a generated CRUD
plan for it. JSON always has method, path, handler, access, status,
lane and lane_reason.
Export the OpenAPI document with openapi¶
uv run hinoki openapi --output openapi.json
uv run hinoki openapi --check openapi.json
uv run hinoki openapi --breaking-against openapi-baseline.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.
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.
Run --check in CI to catch an OpenAPI document that drifted from the code, and
--breaking-against with the last released document before a release. See
OpenAPI for what the document contains.
Show settings with settings¶
uv run hinoki settings
uv run hinoki settings --format json
uv run hinoki settings --example
The target is an application with typed settings or a settings class
(notes.settings:ProjectSettings). Each value is shown with where it came from;
settings.Secret values are redacted. --prefix, --dotenv and --toml
replace the sources the class declares. --example prints a .env.example with
defaults and types, leaving required fields blank and commenting out optional
values with no printable default (secrets, unset values). See
Settings.
Report versions with version¶
uv run hinoki version --verbose
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.
Errors and edge cases¶
- A target that does not import prints an
error:line with the import failure (error: cannot load TARGET: …forroutesandopenapi) and exits non-zero (2 forcheck,routesandopenapi). - Importing the target runs your module-level code; keep import-time side effects out of it.
openapioptions--output,--checkand--breaking-againstexclude each other.doctorwithouthinoki.tomlstill checks the environment and marks the application checks skipped.