CLI
The crossbind package installs one command. Bundler plugins and React Native builds run the build for you; the other commands list licenses, manage the build containers and runners, sign in to crossbind cloud and edit the machine settings.
Commands at a glance
| Command | Does | Touches |
|---|---|---|
build | compiles the project | Docker or a runner, the network, .crossbind/, paths.output |
licenses | lists the licenses of the native dependencies | reads the project; writes only the files you ask for |
clean-deps | deletes dependencies rebuilt from source | .crossbind/deps/ |
docker | manages the toolchain containers | Docker |
runner | starts, removes or scaffolds build runners | Docker (start, delete), a new folder (init) |
login, logout, usage, account delete | your crossbind cloud account | crossbind cloud, ~/.crossbind/credentials.json |
config | the machine settings | ~/.crossbind.json |
Run it from a package script or with npx crossbind. login, logout, usage, account, config and --version (-V) work anywhere; the other commands load the project in the current folder before they read the command line, and fail outside one. --help after a command lists its options. A failure prints a short message; set DEBUG=1 to see the whole error.
build
| Option | Values | Without it |
|---|---|---|
-p, --platform | wasm, wasi, android, ios, darwin, linux, linuxmusl, win32, or host for this machine's desktop platform | wasm, wasi, android and ios; the desktop platforms build only when named |
-a, --arch | wasm32, wasm64, arm64-v8a, x86_64, iphoneos, iphonesimulator, arm64, x64 | every arch but wasm64 |
-r, --runtime | st, mt | both |
-b, --build-type | release, debug | release |
-e, --runtime-env | browser, edge, node, native, wasi, http | target.runtimeEnv from crossbind.config.js; with neither, only the archives |
--rebuild-deps [list] | all, or dependency names separated by commas | prebuilt dependencies |
A list option takes commas or repeats (-p darwin,linux or -p darwin -p linux), and a value outside its list stops with the allowed ones. The target matrix decides which combinations exist: android, ios and the desktop platforms build mt only, wasi and edge builds are single-threaded, and ios and darwin build on a Mac and are skipped elsewhere.
-e names the binaries to make: on wasm, browser, edge and node each give a module and its loader; on a desktop platform, node gives a Node-API addon and native an executable; on wasi, wasi gives a command and http a wasi:http component. Android and iOS take none, since React Native links the archives. See Browser, Node.js and Executables.
--rebuild-deps builds the named dependencies from source into .crossbind/deps/ instead of using their prebuilt archives; CROSSBIND_REBUILD_DEPS does the same from the environment. In a port with a crossbind.build.js recipe, build downloads the pinned upstream source, checks it against the SHA-256 the recipe pins and builds the archives.
Touches: under the default RUNNER, it pulls the pinned toolchain images and runs a container for each step (Remote builds moves the steps elsewhere); ios and darwin compile with Xcode on the Mac. It writes the cache in .crossbind/, the output folder (paths.output, .crossbind/build unless the config names another) and shared caches under ~/.crossbind/, and downloads crates, Conan packages and sources a build needs.
licenses
Prints one line per bundled native dependency - name, SPDX license, native version and source URL - and marks the copyleft ones with !. It reads the project and writes only the files you ask for.
| Option | Does |
|---|---|
--notices [file] | writes a third-party notices Markdown file, THIRD-PARTY-NOTICES.md by default |
--sbom [file] | writes a CycloneDX SBOM: sbom.cdx.json by default, or the path the package declares in crossbind.provenance.sbom |
--json [file] | writes the rows with their license texts, licenses.json by default |
--check | exits non-zero when a license field is missing or not valid SPDX |
--platform <platform> | adds what that platform's artifact links statically beyond the package graph: vendored copies and the toolchain runtime |
-e, --runtime-env node | adds the crossbind runtime an addon of --platform compiles in, or without --platform the one its loader bundles |
--package | with -e node: writes a Node-API package's LICENSE, sbom.cdx.json and package.json license field |
clean-deps
crossbind clean-deps [names...] deletes .crossbind/deps/, the dependencies --rebuild-deps built from source, or only the ones named (by name, package name or alias). The next build goes back to their prebuilt archives unless it rebuilds them again.
docker
One container per toolchain image and project. [image] is web (the default), android, linux or windows.
| Command | Does |
|---|---|
docker create [image] | creates the long-lived container RUNNER=DOCKER_EXEC runs steps in, with the project's base folder and crossbind's cargo and Conan caches mounted |
docker start [image], docker stop [image] | starts or stops it |
docker delete [image] | removes it |
docker run <program> [params...] | runs one program the way a build step runs, in the web image under the current RUNNER, with .crossbind/build as the working folder |
The default, RUNNER=DOCKER_RUN, needs none of these: it starts a fresh container of the pinned image for every step.
runner
| Command | Options | Does |
|---|---|---|
runner start | --role (web, android, linux or windows; default web), --port (8787 to 8790 by role), --host (default 127.0.0.1), --token (default $CROSSBIND_RUNNER_TOKEN, else a new one) | starts crossbind-local-runner-<role> in the local Docker and prints the commands that point builds at it |
runner delete | --role | stops and removes that container |
runner init <platform> | fly, cloudflare, cloudrun or azure; --role; --dir (default crossbind-runner-<platform>-<role>); --vcpu 1 to 4, for cloudflare only | writes a deploy folder and prints its steps with a new token; starts nothing |
How builds use a runner: Remote builds.
login, logout, usage, account
| Command | Does |
|---|---|
login | signs in to crossbind cloud with GitHub: prints a code to enter on github.com, then keeps the token in ~/.crossbind/credentials.json |
logout [--all] | forgets this machine's token and revokes it; --all revokes the tokens of every machine signed in to the account |
usage | this month's cloud build time by image and what is left, and the playground compiles left today |
account delete --yes | deletes the account and signs out every machine; without --yes it deletes nothing |
They talk to CLOUD_URL, https://api.crossbind.dev unless ~/.crossbind.json or CROSSBIND_CLOUD_URL names another. Limits, and what the cloud keeps: Remote builds.
config
| Command | Does |
|---|---|
config get <key> | prints the value and default of <key> and of every key whose name contains it |
config set <key> <value> | sets one key in ~/.crossbind.json, which is rewritten with every key, unset ones at their defaults; an unknown key, or a RUNNER value outside its four, is refused |
config delete <key> | removes a key, so its default applies again |
config list [-t all|system|project] | prints the machine settings (system, the default); all adds the resolved project configuration and project prints it alone, so both need a project |
config keys | lists every key with its description and default |
| Key | Default | Sets | Environment |
|---|---|---|---|
RUNNER | DOCKER_RUN | where toolchain steps run: DOCKER_RUN, DOCKER_EXEC, LOCAL or REMOTE | CROSSBIND_RUNNER |
REMOTE_URL, REMOTE_URL_WEB, REMOTE_URL_ANDROID, REMOTE_URL_LINUX, REMOTE_URL_WINDOWS | - | runner addresses under RUNNER=REMOTE | the same name with a CROSSBIND_ prefix |
CLOUD_URL | https://api.crossbind.dev | the crossbind cloud of the account commands and cloud builds | CROSSBIND_CLOUD_URL |
XCODE_DEVELOPMENT_TEAM | - | the Xcode development team iOS builds sign with | - |
WASI_SDK_PATH | - | a local wasi-sdk, 34 or later, for WASI builds under RUNNER=LOCAL | CROSSBIND_WASI_SDK_PATH |
DOCKER_REGISTRY_MIRROR | - | a registry prefix to pull the pinned images from; the release digest stays | CROSSBIND_REGISTRY_MIRROR |
DOCKER_IMAGE_WEB, DOCKER_IMAGE_ANDROID, DOCKER_IMAGE_LINUX, DOCKER_IMAGE_WINDOWS | - | an image to use instead of the pinned one; without the release digest, builds lose their reproducibility guarantee | CROSSBIND_IMAGE_WEB and the like |
Runner tokens are not keys: CROSSBIND_TOKEN and CROSSBIND_TOKEN_<IMAGE> come only from the environment.
npm create crossbind
A separate package, create-crossbind, scaffolds a project from a template. It asks for a name, a folder and a template; arguments preselect them in order - <dir> <group> <framework|variant> [<variant>] - and -- --help lists the templates. The groups are Web, Mobile, Desktop, Backend, Cloud, Native and Library. It writes the new folder and prints the next steps; it installs nothing.