Shims & versions.

install-shell prepends ~/.tebako/shims to PATH inside a managed block in the shell startup file — idempotent, and removed by tebako-shim uninstall-shell. On Windows the shim directory goes on the user PATH in the registry (HKEY_CURRENT_USER, HKCU). Open a new shell afterwards.

tebako install registers them — registry installs always do; installing a local package file does it only with --shims. tebako uninstall <name> removes the shims and the cache entry. There is no tebako shim add/remove/list — the read-side verb is tebako-shim list.

Two classes of shim share the directory. A payload shim dispatches to a packaged payload, which is the class the rest of this guide describes. A runtime-own shim dispatches to an engine’s own tool with no payload in between, and tebako install <engine>[:<command>] creates it: the bare form registers the interpreter’s own name, and the colon form registers the declared command’s name.

The claims live in ~/.tebako/shims/.runtime-own.yaml, a map from each registered name to the engine and the entry token it boots. tebako-shim list reports them beside the payload shims and marks them [runtime-own]. When a payload provides a name that a runtime-own claim also carries, the payload’s name wins on every dispatch, and a later payload claim displaces the runtime-own one loudly.

Every invocation re-evaluates the chain. The environment beats the project, the project beats the config, and the config beats the publisher’s default.

1. Environment — one shell, one pin.

The variable name is the tool name uppercased, with non-alphanumerics replaced by underscores — a tool mn-cli answers to TEBAKO_MN_CLI_VERSION. The environment holds the highest precedence and is the easiest to undo.

2. Project file — pinned with the code.

The dispatcher walks up from the current directory; the nearest file that pins the command wins. A nearer file that does not mention the command does not shadow a farther one that does. Commit the file with the project.

3. Defaults in ~/.tebako/config.yaml.

The file is hand-edited. Two commands write it: tebako add-registry, and tebako shim use <tool> <pin>, which sets a tool’s default; there is no top-level tebako use.

4. Registry default — the publisher’s word.

If nothing above pins a version, the registry’s own default: entry decides.

The chosen entrypoint declares a runtime requirement. The dispatcher picks the newest compatible runtime already in the cache — no download — or, if none fits, downloads, verifies, and caches one. Pure-language payloads declare a range (>= 3.3, < 5.0); native-extension payloads pin an application binary interface (ABI) line (~> 3.3.0) plus a platform ABI string, and a wrong line is a named error, never a segfault. Entrypoints that need no interpreter — native tools — declare no runtime and get none.

which is read-only: it shows what this invocation would dispatch — payload, where the version came from, image, entrypoint, runtime, mounts, and the final exec argv — without running anything. Output above is representative.

doctor 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). The store-wide diagnostic is tebako doctor, which carries this same report as its dispatch section; tebako-shim doctor remains the dispatcher’s own verb.

disable parks a version — or the whole tool — so dispatch no longer selects it, and enable restores it. The state lives in ~/.tebako/shims/.disabled.yaml: a plain YAML file that can be read or edited.

Leading --jail, --mount, and --no-host tokens are consumed by the dispatcher; everything after them reaches the payload verbatim. The policy grammar is in the jails guide.

See also: Set a jail policy · Debug & logging · Dispatch, in the architecture docs.