ZLM command-line toolchain

Status: preview toolchain guide. ZLM is available only when the downloads page can validate a signed IDE/toolchain release cohort. It is not a stable channel or a promise that every Core-0 or Core-1 construct is implemented.

ZLM is the standalone ZergLang entry point. It manages checked projects, invokes the compiler and runtime, starts the bundled conversational agent, exposes the same project operations over MCP, and installs only explicitly accepted signed updates.

Download, verify, and install

Download the Apple Silicon archive from the downloads page. Copy the displayed SHA-256 value and verify the file before extracting it:

shasum -a 256 zerglang-toolchain-<version>-aarch64-apple-darwin.tar.gz

The output must exactly match the 64-character checksum shown on the release card. Do not install an archive whose name, size, or digest differs. Extract it into its own directory and run the included installer—there is no shell-pipe installer:

mkdir zerglang-toolchain
tar -xzf zerglang-toolchain-<version>-aarch64-apple-darwin.tar.gz \
  -C zerglang-toolchain
./zerglang-toolchain/install.sh

The installer verifies the bundle manifest before activation. By default it keeps immutable generations under ~/.local/share/zerglang/toolchains/, points ~/.local/share/zerglang/current at the active generation, and creates zlc, zlm, zlsync, and zlbench-exec symlinks in ~/.local/bin. Add that command directory to your shell path if necessary:

export PATH="$HOME/.local/bin:$PATH"

ZERGLANG_INSTALL_ROOT and ZERGLANG_BIN_ROOT can select different absolute locations beneath your home directory when running install.sh. The installer refuses relative paths, paths outside your home directory, unsafe symlink ancestors, and non-symlink command collisions. These are the same root rules used by zlm update.

Verify the active installation rather than assuming the archive activated:

zlm version --json
zlm doctor --json

doctor checks that ZLM, the compiler, runtime, bundled Node process, and conversational-agent embed are version-compatible.

Authenticate for conversation

Project checks, builds, and runs are local. Conversation requires a ZergAI device identity and network access:

zlm auth login
zlm auth status --json

Login opens a browser for the device flow and prints a URL and code as a fallback. Use zlm auth login --no-open on a machine where ZLM should not open the browser. A specific workspace can be requested with --workspace <id>. Credentials are user-scoped and stored in a private file; sign out and revoke the device with:

zlm auth logout

If the service cannot be reached, zlm auth logout --local removes the local credential without claiming that the remote device was revoked.

Build by talking to ZLM

Run ZLM with no arguments for an interactive session, or spell the same entry point explicitly:

zlm
zlm chat
zlm chat --prompt "Check this project, explain the first error, and fix it."

The bundled agent can inspect project files and invoke the checked project operations. File writes, builds, and runs require a one-time terminal approval. A non-interactive prompt cannot approve a mutating operation, so it fails closed instead of silently changing the project.

Provider and model can be selected for a session with --provider <name> and --model <name>. Authentication, routing availability, and usage policy still apply; choosing a model flag does not create authority.

Check, build, and run a project

ZLM finds .zerglang/project.json in the current directory or an ancestor. A minimal Core-0 project configuration is:

{
  "schema": "zerglang.project/1",
  "name": "hello",
  "sourceRoots": ["src"],
  "rootModule": "app.main",
  "entrySelector": "main",
  "edition": "core-0",
  "preview": null,
  "defaults": {
    "semantics": "exact",
    "verification": "checked",
    "runTier": "interpreter",
    "buildTarget": "checked",
    "buildOutput": "out/hello.zlm"
  }
}

Place the module app.main beneath src/, then use the deterministic command surface:

zlm check
zlm build
zlm run

check validates the complete configured source closure. build writes the selected checked, C, object, or reflection target. run uses the configured interpreter or JIT tier. Passing extra compiler arguments to these commands uses the lower-level compiler proxy; normal project work should keep policy in project.json so people and harnesses exercise the same build.

Core-1 projects use "edition": "core-1" and must select one cumulative preview: shared, compute, state, flow, or optimize.

Connect Codex or Claude through MCP

ZLM exposes bounded project operations over a local stdio MCP server. Register it with either harness from the project environment where zlm is on PATH:

codex mcp add zerglang -- zlm mcp serve
claude mcp add zerglang -- zlm mcp serve

The server is started by the harness when needed; do not run a second copy for the same stdio session. Its available operations check, build, and run the current ZergLang project and return bounded output. Retrieve the canonical, machine-readable registration contract with:

zlm harness instructions --json

This makes ZLM usable from an external coding harness without merging that harness into the compiler or granting it implicit language authority.

Check, install, or roll back an update

ZLM never silently installs an update. Checking is read-only, while installation is a separate explicit command:

zlm update check
zlm update install

Both commands verify the channel’s signed release cohort against the trust root pinned into the installed ZLM binary. Installation additionally verifies the toolchain archive’s target, version, size, SHA-256 digest, source identity, and internal bundle manifest before atomically activating a new user-scoped generation. The previous accepted generation is retained. Return to it with:

zlm update rollback

Rollback accepts only a previously journaled generation whose receipt and bundle still verify. Add --json to any of the three update commands for a stable automation response. Preview builds follow the preview channel; a stable-looking version would follow stable, but no stable ZergLang channel is currently advertised.

Support matrix

Surface	Current preview support
Host	macOS 15 or newer on Apple Silicon
Package	Signed aarch64-apple-darwin .tar.gz cohort asset
Commands	zlc, zlm, zlsync, and zlbench-exec
Project execution	Interpreter and JIT; AOT project run is reserved
Conversation	Bundled agent plus ZergAI device auth and network access
Harness	Local stdio MCP registration for Codex and Claude
Updates	Explicit check/install/rollback with signed preview authority
Unavailable packages	Windows, Linux, and Intel Mac

Preview limitations

• Stable Core-1 is inactive. Each cumulative preview is partial and remains subject to conformance work.
• entrySelector is currently limited to main; named CLI invocation has not shipped.
• runTier: "aot" is reserved until native executable linking ships.
• Conversational success is not compiler success. Trust only a reported check, build, or run result that the tool actually executed.
• The built-in agent is project-scoped and intentionally bounded. It is not a general shell harness, and non-interactive mutation approval is denied.
• A missing or invalid signed cohort leaves the download and updater unavailable; ZLM does not guess a release asset or fall back to an unsigned package.