REFERENCE · 02

The tebako command, verb by verb.

The tebako command-line interface (CLI) is the packager and the store front end: it presses packages, runs them, traces them, checks them, manages the store and the registries, and publishes payloads. Every usage line below is the shipped binary's own help text.

Build: press.

tebako press -r <root> -e <entry> [-o <output>] [-p <prefix>] [-c <cwd>]
             [-R <ruby>] [-m self-contained|shared-runtime] [-l error|warn|debug|trace]
             [--image <path>:<mount>]... [--bootstrap <path>]
             [--tebako-version <v>] [--prefer-local] [--jail <spec>]
             [--no-install] [--quiet-notices] [--sign[=<keyid>] | --no-sign]
             [--format dwarfs|limnifs] [--compose <tebako.yaml>]
             [--carry all|none|<name,...>] [--share <name,...>]

The lean and fat mode names stay accepted as deprecated aliases of shared-runtime and self-contained. A suite presses one package with N commands:

tebako press --suite <suite.yaml> [-o <output>] [-p <prefix>] [-R <ruby>]

Signing at press resolves through the settings registry — the CLI flag wins, then the environment, then the compose document. Only the CLI may name a key. The task-oriented walkthrough is the Package a Ruby app guide.

Run: run.

tebako run <pkg> [--jail <spec>] [--mount <host:mount:ro|rw>]... [--no-host]
            [--] [<args>...]

Everything after -- reaches the payload verbatim; the flags before it shape this run only. The guide is Run a packaged app.

Trace: run, cover, import, explain.

The trace verbs form the interception-bus toolkit; the task-oriented walkthrough is the Trace a packaged app guide.

tebako trace run runs a package under the record policy with the trace bus armed and synthesizes a suggested manifest — commented YAML on stdout, never applied:

tebako trace run <pkg> [--capture <path>] [--out <path>] [--] [<args>...]

tebako trace cover subtracts the inside stream from an outside capture and reports the escapes (exit 0 clean, 1 escapes, 2 error):

tebako trace cover --inside <tfs.json> --outside <retrace.json> --prefix <path>
                   [--pid N] [--window SECS] [--exclude-probes] [--json] [--layer libc|kernel]

tebako trace import procmon converts a procmon CSV export into the retrace-shaped JSON that cover consumes (exit 0 converted, 1 zero entries, 2 error):

tebako trace import procmon <capture.csv>

tebako trace explain replays a capture into the hop chain and names the first red hop (exit 0 clean, 1 red hop, 2 error):

tebako trace explain <capture.jsonl>

Check.

The verb runs the payload’s in-image acceptance checks against a name, an image, a package, or a compose document:

tebako check <name | image.tfs | package | tebako.yaml>
             [--check <c>] [--list] [--record] [--keep-scratch]
             [--runtime <exe> --runtime-image <env.tfs>]

The guide is Check a payload.

The store: cache, install, uninstall, info, inspect.

tebako cache list [--json]
tebako cache prune [--all] [--older-than Nd]
tebako install <ref | name[@ver]>
tebako uninstall <name>
tebako info [topic] [--remote] [--json]
tebako inspect <artifact> [flags]

tebako install installs a payload and registers its shims; tebako uninstall removes the shims and the cache entry. tebako info reports on the store and its contents — the topics are system, runtimes, payloads, shims, registries, and store. tebako inspect reads a single artifact; --contract prints the contract card: the era, the contract versions, mount_root, the ABI, and the trust verdict. The guide is info & inspect.

Registries: add, list, update.

tebako add-registry <ref>
tebako list-registries
tebako update-registries

tebako add-registry registers a tpkg-registry.yaml; tebako update-registries refreshes the dispatch-time registry cache. The guides are Publish to your own registry and Curate a local library.

Publish.

tebako publish --name <app> [--version <v>] --release tfs:github:<owner>/<repo>[:<tag>]
               (--payload <path> | --payload <triplet>=<path>)...
               [--standalone <triplet>=<path>]... [--sign[=<keyid>]]
               [--upload-mirror <dir>] [--tap <org/homebrew-tap> [--tap-dir <dir>]]
               [--registry-out <path>] [--skip-verify]

The publisher’s GitHub releases are the storage; the command writes the index consumers add. The walkthrough is the publish guide.

Bundle.

tebako bundle <name[@ver]> --output <dir> [--config <org.yaml>] [--archive tar.gz]

The verb assembles an offline bundle: the payload’s whole dependency closure plus the runtimes it needs, gathered into one directory (optionally archived) that installs and runs with no network. Bundling draws from the local store and refuses a partial set by name — the closure is cached first.

Diagnose: doctor.

tebako doctor [--json]

The verb is the read-only diagnostics surface: five sections (store, dispatch, network, trust, registries) carry a named verdict on every check, with exit 0 when healthy and 1 with a problem count. --json prints the same report as a machine-readable document. The dispatch section is the tebako-shim doctor report rendered in place.