GUIDES · 12

Debug & logging.

Everything tebako logs goes to stderr, in one format, under one switch: tebako[<pid>] <level> <component>: <event> <k=v>… — stdout belongs to the payload, and logs never touch it.

The switch.

Turn logging on with TEBAKO_DEBUG:

$ TEBAKO_DEBUG=debug tebako install metanorma
$ TEBAKO_DEBUG=warn,resolve=trace tebako install metanorma

Levels: off (default), error, warn, debug, trace. A comma list sets a base level plus per-component exceptions. 1/true/yes mean debug; 0/false/no mean off.
The components: preload, tfs, driver, shim, bootstrap, cli, pkg, resolve. TEBAKO_DEBUG_COMPONENTS=resolve,cli filters output to a subset.
TEBAKO_DEBUG_FILE=<path> appends to a file instead of stderr; %p in the path expands to the pid, so parallel runs do not interleave.
Legacy: any non-empty TEBAKO_DEBUG_TFS means tfs=debug. Payload contents and key material are never logged. For a structured capture — one JSON event per interception decision, machine-consumable — arm the trace bus instead: see Trace a packaged app.

A worked session: a failing install.

A failing install under TEBAKO_DEBUG=debug looks like this:

$ TEBAKO_DEBUG=debug tebako install metanorma
tebako[81234] debug cli: install name=metanorma
tebako[81234] debug resolve: registry cache fresh age=3h file=~/.tebako/registries/9f2c….yaml
tebako[81234] debug resolve: select metanorma version=1.2.3 artifact=metanorma-1.2.3.tfs
tebako[81234] error resolve: download failed status=404 url=https://github.com/…/releases/download/…

Read a line left to right: pid, level, component, event, then key=value detail. This trace says the registry index named an artifact the release page does not have — a publisher-side break, not your machine. Log output shown is representative.

doctor: the first thing to run.

The diagnostic verb is tebako-shim doctor:

$ tebako-shim doctor

It checks that the shim directory is on PATH, that every shim resolves, that payload records and their trust anchors exist, that the config parses, that registries are fresh, and that the runtime cache is intact. It ends with no problems found (exit 0) or a problem count (exit 1). When a shim misbehaves, run this before anything else. Note the binary: there is no tebako doctor — the verb is tebako-shim doctor.

"The version the publisher just shipped isn’t there."

Registry indexes are cached for dispatch with a 24-hour TTL. A stale cache is the most common cause of a missing new version — check the state, then refresh:

$ tebako info registries
tfs:github:tebako-packages/metanorma   fetched 3 h ago    fresh
tfs:github:tamatebako/hello            fetched 26 h ago   stale
$ tebako update-registries

Output representative.

Exit codes.

Every loader failure prints a one-line reason before exiting — read that line first. The everyday two: 69 (something could not be fetched — check TEBAKO_OFFLINE first) and 73 (a malformed jail policy — fail closed, nothing mounted). The complete table — all loader codes 64 through 79, plus the three outside the block — lives in the reference: Exit codes.

CI logs.

TEBAKO_NO_PROGRESS=1 — or NO_COLOR, or TERM=dumb — switches progress rendering to plain lines that read cleanly in a build log.