Hatch

Build, run, and ship Wren programs as standalone projects. Powered by the WrenLift runtime.

---

Wren shines as an embedded scripting language: small, fast to integrate, designed to slot into games, editors, and tools written in C or C++. That's the use case Wren is built for, and it's a good one.

Hatch offers a complementary path. When your project is Wren (a CLI, a service, a library shared between Wren programs), Hatch plus WrenLift is the toolchain that lets you write it, package it, and run it on its own. Same language, same idioms, different deployment story.

If you know Wren, you already know how to use this. What you need is a place to put your code and a way to ship it.

Install

The hatch binary ships alongside the WrenLift runtime: one install gives you both wlift (the runtime) and hatch (this CLI) on your $PATH.

curl -fsSL https://raw.githubusercontent.com/wrenlift/WrenLift/main/install.sh | bash

That fetches the latest GitHub Release, verifies the SHA256, and drops both binaries into ~/.local/bin. Override with INSTALL_DIR=/usr/local/bin or pin a tag via WLIFT_VERSION=v0.1.0.

macOS (arm64, x86_64) and Linux (x86_64, aarch64) are supported. Windows users can grab the binaries manually from Releases.

Or from source:

git clone https://github.com/wrenlift/WrenLift
cd WrenLift
cargo build --release
# binaries land in target/release/{wlift,hatch}

wlift --version and hatch --version should both print 0.1.0.

Your first Wren project

Create an empty directory and let hatch scaffold it:

hatch init hello-wren
cd hello-wren

You'll find two files:

hello-wren/
├── hatchfile      # project manifest (TOML)
└── main.wren      # entry point

main.wren is a regular Wren program. Open it:

// Entry point for package 'hello-wren'. `hatch run` executes this file.
System.print("hello from hello-wren")

Run it:

$ hatch run
hello from hello-wren

That's your full local loop: write Wren, run Wren.

Add more Wren to the project

Drop another .wren file next to main.wren:

// counter.wren
class Counter {
  construct new() { _n = 0 }
  tick() { _n = _n + 1 }
  count { _n }
}

Import it from main.wren:

// main.wren
import "counter" for Counter

var c = Counter.new()
for (i in 0..4) c.tick()
System.print("count: %(c.count)")

hatch discovers every .wren file in the workspace on its own. If you want explicit control over module order, list them in the hatchfile:

name    = "hello-wren"
version = "0.1.0"
entry   = "main"
modules = ["counter", "main"]

Run again:

$ hatch run
count: 5

Package it

When you're ready to ship:

$ hatch build
built 1241 bytes from . → ./hello-wren.hatch

The resulting hello-wren.hatch is a single file that carries the compiled bytecode for every module in the project. Hand it to someone else and they can run it without the source tree:

$ hatch run ./hello-wren.hatch
count: 5

Curious what's inside?

$ hatch inspect hello-wren.hatch
hatch: hello-wren 0.1.0
  entry:   main
  modules: counter, main
  sections:
       Wlbc        861 bytes  counter
       Wlbc        412 bytes  main

Depend on other hatches

A .hatch file is a reusable library. Once you have a library hatch somewhere on disk, you can preload it before running your app:

hatch run --with ../some-lib/some-lib.hatch

Declarative dependencies in the hatchfile (and a hatch tidy resolver that fetches them from a registry) are next. The CLI already shows the planned surface:

$ hatch add some-lib 0.2
hatch: not yet implemented: add some-lib@0.2 — resolver + registry
       lookups are planned; see the README roadmap

hatchfile

Every Wren project has one. Today's fields:

name    = "hello-wren"
version = "0.1.0"
entry   = "main"                      # module to run

modules = ["counter", "main"]         # install order; auto-filled if empty

# [dependencies]                      # not yet wired
# std  = "0.3"
# http = { version = "0.1", features = ["tls"] }

Commands today

• hatch init [DIR] — scaffold a hatchfile + main.wren.
• hatch build [DIR] — pack the workspace into a .hatch.
• hatch run [TARGET] [--with PKG] — build + run, or run a pre-built .hatch. --with preloads dependency hatches.
• hatch inspect PACKAGE — print manifest + section listing.

add / remove / tidy / get / publish are stubbed and print a roadmap message; the resolver and registry client are where they live.

What lives in this repo

This is the ecosystem repo, not a Rust project. The hatch CLI source lives in WrenLift so one install gets you both binaries. What you'll find here:

• packages/ — the official standard-library hatches (std, http, json, test, …) as they land.
• index.toml — a git-readable mirror of the live hatch catalog. Regenerated automatically from the Supabase-backed packages table every few hours via .github/workflows/sync-index.yml. Don't edit by hand; publish your package with hatch publish instead.
• The future home of the registry service, ecosystem docs, and any dev tools that outgrow the single-binary CLI.

License

MIT.