The hub command

hub provisions the shared dependency tree and manages the module checkouts of a SushiStack workspace. The one thing it builds is the desktop application in sushihub/gui, which belongs to the workspace rather than to a module. Every module has its own CLI: sr (sushiruntime), se (sushiengine), sa (sushiai), sb (sushiblas).

Layout

sushihub/cli/
  sushistack/            the Python package behind `hub`
    cli.py               the Typer application: one function per subcommand
    config.py            workspace root, the workspace file, the packaged defaults
    gui_config.py        the desktop application's profile, config and root
    gui_env.py           its build environment, vcvars snapshot included
    services/            module lifecycle, Sushi Account, releases, the licence file, the gui build policy
    setup/               the dependency engine: manifests, package managers, toolchains, the pipeline
    defaults.toml        defaults for the [tool], [cli] and [identity] tables
    manifests/           dependency fragments this package ships (*.deps.toml)
  install.py             installs `hub` into a pipx venv and injects sushicore
  pyproject.toml

Commands

--json and --describe are global: they go before the subcommand, and no row below repeats them. See "Machine-readable output".

Tab completion: run hub --install-completion once.

Machine-readable output

hub --json <command> writes one JSON event per line to stdout and nothing else there. Everything a human would read instead — the setup progress bar, a config file rendered before it is written — goes to stderr, so a caller parses stdout line by line and never has to strip a table out of it. Every command ends with one result event carrying its exit status and whatever it computed: hub --json status puts the module list there, hub --json home the workspace and dependency paths. The status payload's shape is fixed by ../contract/status.schema.json. A question becomes a prompt event answered by one line on stdin.

hub --describe prints the command catalogue instead: every subcommand, its arguments and options with their types, defaults and choices. It is a serialisation of the Typer application, not a second declaration, so a new hub command shows up in the catalogue the moment it exists.

Both halves are JSON Schema in ../contract/, and ../contract/README.md writes out the event shapes, the stdout rule and the prompt rule for whoever is on the other end.

Signing in

sushiengine is sold; the other four modules are not. hub login is how a machine proves a licence, and nothing else in hub needs it: cloning an open-source module asks only for a Git identity.

hub login asks Sushi Account for a device code, prints it with the page to type it into, opens that page in the browser, and polls until you approve it there. What comes back — an access token, a refresh token and an expiry — goes into the operating system's credential store through keyring, under service sushistack and username sushi-account. A later command that needs the account refreshes the access token when it is within 30 seconds of expiry; when the refresh is refused, the stored session is dropped and the command says nobody is signed in.

Sushi Account lives at https://account.sushisystems.io, from [identity] url in config.toml. SUSHI_ACCOUNT_URL overrides it, which is how the tests point every Sushi Account call at a fake server on 127.0.0.1. The six endpoints are written out in ../contract/sushi-account.md; sushiweb has not built them yet.

Binary installs

hub add sushiengine decides between the two forms rather than being told. It asks the private repository whether this machine's Git identity reaches it, with git ls-remote --exit-code under a 15-second timeout. If it does, the module is cloned like any other. If it does not, hub needs a Sushi Account session: with one it downloads the release, without one it names both ways in and stops. --binary skips the question and goes straight to the release. The other four modules are open source and have one path; --binary on any of them is refused.

The download is what sushiweb signed a URL for. hub streams it, refuses to unpack it when either the size or the sha256 differs from what Sushi Account declared, unpacks it into a directory beside <workspace>/sushiengine, and renames that over the module last, so a download that fails leaves the install that was there untouched. The release carries sushi-release.json at its top level: that file is what makes the directory a binary install, and hub status reads the version out of it ("binary 1.4.2"). Beside it hub writes sushi-licence.jwt, the licence token Sushi Account issued, which the engine reads at start-up and verifies offline against Sushi Account's JWKS.

A release brings its own sushiruntime and sushiblas, so it declares no dependency fragment and nothing provisions after it: a licensed user never downloads a SYCL toolchain. It also installs no module CLI; se arrives inside the package.

hub update sushiengine asks for the latest release, says the install is already the latest when the versions match, and downloads the new one and writes the licence file again when they do not. hub add sushiengine on a directory that is already a binary install leaves it alone.

How dependencies are chosen

hub install merges every *.deps.toml fragment the sushistack package ships with each present module's own cli/sushistack.deps.toml, keeps the entries that name a package for the current platform, and installs the ones that are missing. No dependency name lives in the installer code. The SYCL toolchains are sushiruntime's entries, not this repository's; the GPU toolkit is on for every workspace and follows the detected GPU vendor (sushistack/setup/selection.py); the base fragment carries only cmake, ninja, gtest, opencl and pkgconf.

A shipped fragment is owned by the name in its filename, with base.deps.toml the exception that owns nothing and is owned by shared. So gui.deps.toml, which names the desktop application's imgui, glfw3 and nlohmann-json, is owned by gui and hub doctor groups those three rows under it.

The toolchain selection follows the same rule: a component is installed when a present module's fragment declares a dependency of that name, so an empty workspace gets the base tools alone. hub add and hub link run the provision pipeline for the module they bring in, unless you pass --skip-install.

Files it reads and writes

Where sushicore comes from

hub imports sushicore for its console, its config schema and its workspace helpers. The package is not on any index; install.py injects the checkout under <workspace>/sushicore into the pipx venv, editable. SUSHICORE_DIR or hub link sushicore <path> points it elsewhere. See ../../sushicore/docs/README.md.