pure build

pure build uploads your project to api.pure.dev, compiles the entry point to a native binary in the cloud, streams the compile log, and downloads the finished executable.

pure build <entry> [options]

The current directory is packaged as a gzipped tarball and uploaded. node_modules and .git are excluded, but package.json and your lockfile are kept so the server-side pre-command can install dependencies. The build never runs on your machine — no local toolchain is required.

Arguments

| Argument | Description | |---|---| | <entry> | Entry file to compile, relative to the source directory (e.g. server.ts or src/main.ts). |

Options

| Flag | Default | Description | |---|---|---| | -o, --out <file> | ./<entry-stem> | Path to write the downloaded binary. For src/main.ts the default is ./main. If that path already exists, a " (n)" suffix is appended (like a pasted duplicate in Windows Explorer) rather than overwriting it — see Build Output. | | -f, --force | off | Overwrite --out (or the default path) if it already exists, instead of auto-incrementing. | | --target <kind> | binary | Output artifact: binary (a standalone executable) or node-addon (a Node.js native addon). | | --libc <c> | musl | C library for the compiled binary: musl (fully static, runs on any Linux host) or glibc (dynamically linked, needs glibc on the run host). | | --glibc-version <v> | 2.29 | Minimum glibc version to target, e.g. 2.31. Only valid with --libc glibc — the binary runs on any host with glibc at or above this version. 2.29 is also the floor: a lower value is silently raised to it (Pure’s own runtime requires glibc ≥ 2.29 to link). Ignored for a non-Linux --platform. | | --platform <p> | auto-detected | Output platform: linux-x64, linux-arm64, macos-x64, or macos-arm64 Experimental — the platform your compiled binary targets, independent of which machine you run pure build from. Defaults to the OS/architecture of the machine running pure build. See OS support for macOS caveats. | | --pre <cmd> | — | Pre-command run server-side before compiling, e.g. "npm ci". | | --env KEY=VAL | — | Environment variable for the build sandbox. Repeatable. | | --dir <path> | current dir | Source directory to upload instead of the current directory. | | --api-key <key> | — | API key override (see authentication order). | | --oidc-token <tok> | — | A GitLab (or other supported CI provider’s) id_token instead of an API key — the project/branch must be connected first on the dashboard’s Integrations page. Requires --account/--org below. Takes precedence over --api-key/PURE_API_KEY when set. Also settable via PURE_OIDC_TOKEN. See Authentication → OIDC. | | --account <id> | — | Required with --oidc-token: the user id that made the connection to authenticate against (shown on the dashboard’s Integrations page). Also settable via PURE_ACCOUNT_ID. | | --org <id> | — | Required with --oidc-token: the org that connection bills to. Also settable via PURE_ORG_ID. | | --api-url <url> | wss://api.pure.dev/ws | API endpoint override. Also settable via PURE_API_URL. | | --type-profile-collect | off | Instrument the build to record a per-site type/call profile as your program actually runs — a form of profile-guided optimisation that adapts at runtime rather than needing an offline training pass. Run the downloaded binary with PURE_TYPE_PROFILE_OUT=<path> set to dump the collected profile as JSON. Combinable with --type-profile-path (guide this build with a prior profile while also recording fresh data from this run). | | --type-profile-path <path> | — | Load a profile previously collected with --type-profile-collect to guide this build’s code generation with real call/type data. Must be a path inside --dir — it travels inside the uploaded tarball, the same constraint <entry> has. | | --train <workload> | — | Two-pass profile-guided optimisation trained on your workload: builds instrumented, runs <workload> (an executable, invoked with the instrumented binary’s path as argv[1] and $PURE_TRAIN_BIN), then rebuilds with the merged profile applied to every crate. Roughly 2x the build time. Must be a path inside --dir, same constraint as --type-profile-path. Purely opt-in — there’s no separate flag to disable it; if you don’t pass --train, nothing about your build changes. |

Release builds also get a generic profile-guided optimisation pass applied to Pure’s own shared runtime code automatically — no flag needed, and it never affects your build’s correctness (any problem with it silently falls back to a plain build). --train supersedes it with one trained specifically on your own workload.

Examples

Compile the file in the current directory:

pure build server.ts

Production build to a specific path:

pure build src/main.ts --out ./dist/server

Custom install step and build-time environment:

pure build app.ts --pre "npm ci" --env NODE_ENV=production --env TZ=UTC

Upload a different directory:

pure build main.ts --dir ./service

Cross-compile a macOS binary from any machine Experimental:

pure build server.ts --platform macos-arm64

Collect a type profile from a real run, then rebuild guided by it:

pure build app.ts --type-profile-collect --out ./app.instrumented
PURE_TYPE_PROFILE_OUT=./profile.json ./app.instrumented   # exercise it however you normally would
pure build app.ts --type-profile-path ./profile.json --out ./app

Train on your own workload:

pure build app.ts --train ./bench.sh   # ./bench.sh must be inside the uploaded --dir

What it prints

Progress (upload size, queue position, “Wrote …”) is written to stderr; the streamed compile log is written to stdout. This means you can capture just the compiler output with a normal redirect:

pure build src/main.ts > build.log

Exit codes

| Code | Meaning | |---|---| | 0 | Build succeeded and the binary was written | | 1 | Invalid arguments, authentication failure, or a build/compile error |

Environment variables

| Variable | Description | |---|---| | PURE_API_KEY | API key to use (overridden by --api-key, overrides pure login). | | PURE_OIDC_TOKEN | GitLab (or other supported CI provider’s) id_token to use instead of an API key (overridden by --oidc-token; takes precedence over PURE_API_KEY/pure login when set). Requires PURE_ACCOUNT_ID/PURE_ORG_ID. | | PURE_ACCOUNT_ID | Required with PURE_OIDC_TOKEN/--oidc-token (overridden by --account). | | PURE_ORG_ID | Required with PURE_OIDC_TOKEN/--oidc-token (overridden by --org). | | PURE_API_URL | API endpoint (overridden by --api-url). | | PURE_TYPE_PROFILE_OUT | Not read by pure build itself — read by a binary built with --type-profile-collect, at runtime, on exit. Set it before running that binary to write the collected profile to <path> as JSON, ready to pass to a later build’s --type-profile-path. |