GUIDES · 14

Debug & logging.

Tebako logs everything to standard error (stderr), in one format, under one switch; standard output (stdout) belongs to the payload, and log output never touches it.

The TEBAKO_DEBUG switch.

Logging is turned on with TEBAKO_DEBUG:

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

The level names are off (the default), error, warn, debug, and trace. A comma-separated list sets a base level plus per-component exceptions. The values 1/true/yes mean debug, and 0/false/no mean off.
The component names are preload, tfs, driver, shim, bootstrap, cli, pkg, resolve, and 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 process identifier (pid), so parallel runs do not interleave.
The legacy spelling remains valid: any non-empty TEBAKO_DEBUG_TFS means tfs=debug. Payload contents and key material are never logged. For a structured capture — one machine-consumable JSON (JavaScript Object Notation) event per interception decision — the trace bus is armed instead; Trace a packaged app describes the workflow.

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/…

Each line reads left to right as the pid, the level, the component, the event, and then key=value detail. This trace says that the registry index named an artifact the release page does not have; the break is on the publisher’s side, not on the local machine. Log output shown is representative.

The doctor diagnostic.

The diagnostic verb is tebako doctor:

$ tebako doctor

The command runs five read-only sections — store, dispatch, network, trust, and registries — and prints a named verdict for every check. It verifies the store layout and lock health, the presence of the shim directory on PATH and of every shim, the existence of payload records and their trust anchors, the parseability of the config, the freshness of the registries, and the integrity of the runtime cache. It ends with no problems found (exit 0) or a problem count (exit 1). When anything misbehaves, this command is the first one to run.

tebako doctor shipped in v2.8.0. tebako-shim doctor still exists and reports the shim layer only (missing/corrupt records, routing); the dispatch section of tebako doctor is that same report, rendered in place.

The version the publisher just shipped is missing.

Registry indexes are cached for dispatch with a 24-hour time-to-live (TTL). A stale cache is the most common cause of a missing new version, so the freshness state is checked first and the cache is refreshed next:

$ 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, and that line is the first thing to read. The two everyday codes are 69 (something could not be fetched — the TEBAKO_OFFLINE setting is checked first) and 73 (a malformed jail policy — the run fails closed and nothing mounts). The complete table — all loader codes 64 through 79, plus the three outside the block — lives in the reference: Exit codes.

CI logs.

In a continuous integration (CI) log, TEBAKO_NO_PROGRESS=1 — or NO_COLOR, or TERM=dumb — switches progress rendering to plain lines that read cleanly.