truewire.toml reference

A Truewire project is a directory holding a truewire.toml. Every command finds the nearest one above the working directory, or takes --project PATH.

[project]
name = "petstore"            # required. Also the default Python package name.

[spec]
dir = "spec"                 # default "spec": holds endpoints/ and schemas.json

[secrets]                    # optional: credential variable *names*, never values.
required = ["PETSTORE_API_KEY"]

[cores.default]              # one table per symbolic core name a router.json can declare.
meta = { type = "object", properties = { public = { type = "boolean" } }, additionalProperties = false }

[python]
package = "petstore"         # default: [project].name
src = "src"                  # default "src": the package lives at <src>/<package>
name = "Petstore"            # root class name; default: PascalCase of [project].name
backend = "backend.py"       # optional: a module exporting `generator`, a Generator subclass
ruff = "ruff.toml"           # optional: formatter config; default is the one shipped with truewire
pyright = false              # run pyright after generate; also implied by a pyrightconfig.json

[python.cores.root]          # the core the root router.json names (usually "root")
base = "petstore.core:ClientBase"

[python.cores.default]       # every other symbolic core: base class + how children get the transport
base = "petstore.core:Endpoint"

Sections

• [project]: name is required. It names the project in output and is the default for [python].package.
• [spec]: dir relocates the spec tree. truewire check, examples, surface, mock and generate all read <dir>/endpoints/**/endpoint.json, <dir>/**/router.json and <dir>/schemas.json.
• [secrets]: variable names only. truewire standards uses them to flag a recorded example that leaked a real credential-shaped value.
• [cores.<name>]: the JSON Schema every endpoint's meta must satisfy when its nearest router.json resolves to <name>. Omit meta for a core that reads nothing per call.
• [python]: where the generated package goes and how it is finished. Only python is a target today.
• [python.cores.<name>]: base is module.path:Class, the hand-written class every generated endpoint under that core subclasses; the module is imported during generation to introspect its new() signature. children maps a composed child attribute to the field it receives the transport from, for cores whose children need a different connection.
• [[python.extras."<router node>"]]: hand-written classes folded into a generated router node (file, class, optional replaces).

Generated state

generate writes .truewire/python-files.json, the manifest of files it owns. Files not in the manifest are never deleted; generate --check compares the plan to it, and generate --delete removes only what it owns. Add .truewire/ to .gitignore.