CLI tooling
For HTTP projects, zy serve [--host=127.0.0.1] [--port=8000] [--project=directory]
loads server.zy and local configuration. See HTTP servers and MongoDB.
The examples use go run .; replace it with your built zy executable after installation.
| Command | Result |
|---|---|
go run . run file.zy arg | Execute a script; args() contains arg |
go run . check file.zy | Validate syntax, known type contracts, control-flow context, and imports |
go run . init my-app | Create a project manifest, entry and starter test |
go run . test [path] | Run isolated named tests or assertion scripts |
go run . add ../package | Snapshot and lock a self-contained local package |
go run . check --json file.zy | Emit a versioned, source-free diagnostic result for tooling |
go run . fmt file.zy | Print formatted source to stdout; leave the file untouched |
go run . fmt -w file.zy | Replace the file with formatted source |
go run . fmt --check file.zy | Exit 1 and print its path if formatting is needed; leave it untouched |
go run . --help | Show usage |
go run . -v / --version / -V | Show the development version |
go run . lsp | Serve the local language-server protocol over stdio |
zy file.zy remains equivalent to zy run file.zy. Put CLI flags before the filename. fmt accepts exactly one file; -w and --check are mutually exclusive. The formatter does not follow imports or execute code.
Formatter contract
The formatter uses four spaces per open brace, bracket, or parenthesis, normalizes inline operator/comma/colon spacing, expands nonempty statement blocks, and separates statements that share a line. Existing blank lines and comments remain in place. Line endings outside literals become LF, and nonempty output ends with a newline.
A lossless lexeme layer retains raw string escapes, numeric/network spelling, annotations, named labels, and source trivia. The formatter parses first, then verifies that non-newline tokens and the full position-independent syntax structure remain identical. This protects bare return and expression boundaries. If expanding a layout would change the parse, it retains the original statement layout while normalizing safe spacing. Formatting is idempotent; invalid source is rejected.
The formatter does not impose a maximum line width or reorder declarations. Function argument lists do not currently accept arbitrary line breaks, so long calls remain on one line. In VS Code, Toggle Word Wrap (Alt+Z) makes those lines readable without changing source.
-w prepares and syncs a temporary sibling file, preserves permission bits, checks for intervening content changes, then renames the prepared file over the source. It refuses symbolic links when rewriting. This is a best-effort concurrent-edit check, not a file lock. Replacement changes file identity; hard links, ownership, extended attributes, and ACLs are not guaranteed to survive. Use stdout mode when those properties matter. Replacement atomicity follows the operating system’s rename semantics.
Checks and exits
check reads imported source, validates declarations and known type contracts, rejects missing dependencies and cycles, and enforces module bounds. It never executes code. Dynamic expression names/values, native results, input data, and policy failures still require execution to validate. See projects for manifest-based entry selection, tests, and dependency integrity checks.
Direct executable exit codes:
- 0: success, help, version, or already formatted.
- 1: script/I/O error, failed assertion, or formatting needed in
fmt --check. - 2: invalid CLI invocation.
The Go launcher may wrap an executable’s nonzero exit status; use a compiled binary when consuming exact exit codes.
run --timeout=2s and check --timeout=2s set a cooperative deadline before loading source. Parsing and host I/O are not forcibly interrupted; graph traversal and evaluation check cancellation. fmt has no deadline flag and accepts regular files up to 1 MiB.
Suggested development loop
go run . fmt -w examples/modules/main.zy
go run . fmt --check examples/modules/main.zy
go run . check examples/modules/main.zy
go run . examples/modules/main.zy
go test ./...The VS Code preview provides highlighting, snippets, and an opt-in language client. See diagnostics for saved-file JSON integration and release tooling for archive generation and version policy. Public distribution is pending.