Getting started

Zy runs .zy files locally. You need Go 1.22 or later to build from source. Check with go version, then open a terminal at the repository root.

Run without building a binary

go run . examples/getting-started.zy

Expected output:

Hello, World!

The script contains:

let name = "World"
print("Hello, " + name + "!")

Build a binary

Windows PowerShell:

go build -o bin/zy.exe .
.\bin\zy.exe examples\hello.zy

Linux or macOS:

go build -o bin/zy .
./bin/zy examples/hello.zy

Build outputs belong in bin/, which Git ignores. No additional runtime libraries or API keys are needed for the bundled examples.

Install the global Windows command

From this checkout, run:

.\tools\install.ps1
zy -v
zy --help

The installer builds zy.exe into your user .local\bin directory and adds that directory to your user PATH if needed. No administrator access is required. Run the installer again after pulling language changes to update the executable. Restart existing terminals if they have an older PATH. The script also updates PATH in the shell running it. A custom destination is supported with -InstallDir.

With Zy installed, commands work from any folder:

zy run C:\path\to\script.zy
cd C:\path\to\backend
zy serve

-v, -V, and --version show the version. serve still selects the current project directory unless --project is supplied.

Explore examples

go run . examples/hello.zy
go run . examples/network.zy
go run . examples/features.zy
go run . examples/tutorials/01-basics.zy

The networking example uses native IP/CIDR values and simulated agents. The tutorial guide explains the teaching scripts and expected output. Open examples/errors_demo.zy to choose a diagnostic demonstration.

Write a network check

let office = 10.20.0.0/16
let client = 10.20.64.25

if client in office {
    print("Allowed")
} else {
    print("Outside office network")
}

Save as check.zy using UTF-8 without a byte-order mark, then run go run . check.zy. It prints Allowed.

Know the current behavior

Division returns a Float: 72 / 100 returns 0.72. Use div(72, 100) for integer division. Integer arithmetic is exact within the signed 64-bit range and reports overflow. Ranges and subnet splits are limited to 65,536 items.

The CLI supports run, dependency-aware check, conservative fmt, --help, and --version. Run go run . run --timeout=2s examples/hello.zy for a cooperative deadline. Script arguments follow the filename and are available through args(). See CLI tooling for formatter modes and local modules to share functions between scripts.

Continue with the practical workflows to validate local JSON inputs.

Agent methods return placeholders, ~ uses substring keyword matching, and security helpers print messages. Read status and limitations for details.

Troubleshooting

Any plain-text editor works. The VS Code preview adds highlighting, brackets, snippets, and an opt-in language server for unsaved-file diagnostics and formatting. The release guide covers local archive builds and running binaries without Go.

For development, run go test ./..., go vet ./..., and go build ./.... Continue with the language reference or contributor guide.