From f616326383d942c30e54167939f3153d22414a53 Mon Sep 17 00:00:00 2001
From: sergeych <real.sergeych@gmail.com>
Date: Fri, 5 Dec 2025 21:46:19 +0100
Subject: [PATCH] docs on cli tool, restored cli building tools

---
 bin/local_release                |   6 +-
 distributables/lyng-linuxX64.zip |   4 +-
 docs/lyng_cli.md                 | 141 +++++++++++++++++++++++++++++++
 3 files changed, 146 insertions(+), 5 deletions(-)
 create mode 100644 docs/lyng_cli.md

diff --git a/bin/local_release b/bin/local_release
index d9baccb..6990157 100755
--- a/bin/local_release
+++ b/bin/local_release
@@ -21,9 +21,9 @@ set -e
 
 file=./lyng/build/bin/linuxX64/releaseExecutable/lyng.kexe
 
-#./gradlew :lyng:linkReleaseExecutableLinuxX64
-#strip $file
-#upx   $file
+./gradlew :lyng:linkReleaseExecutableLinuxX64
+strip $file
+upx   $file
 cp $file ~/bin/lyng
 cp $file ./distributables/lyng
 zip ./distributables/lyng-linuxX64 ./distributables/lyng
diff --git a/distributables/lyng-linuxX64.zip b/distributables/lyng-linuxX64.zip
index adf0bfc..397f21b 100644
--- a/distributables/lyng-linuxX64.zip
+++ b/distributables/lyng-linuxX64.zip
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:36a47f3a4b1bdbe4ce76ad512b7c6e1b48e8da165e2aceff05c9c5a3928ad27d
-size 1650617
+oid sha256:62b8555ed80ddcb2553e0d901d4c5a0b61f90bc365c9881d642943a89fbe750f
+size 1858204
diff --git a/docs/lyng_cli.md b/docs/lyng_cli.md
new file mode 100644
index 0000000..ccd096d
--- /dev/null
+++ b/docs/lyng_cli.md
@@ -0,0 +1,141 @@
+### Lyng CLI (`lyng`)
+
+The Lyng CLI is the reference command-line tool for the Lyng language. It lets you:
+
+- Run Lyng scripts from files or inline strings (shebangs accepted)
+- Use standard argument passing (`ARGV`) to your scripts.
+- Format Lyng source files via the built-in `fmt` subcommand.
+
+
+#### Building on Linux
+
+Requirements:
+- JDK 17+ (for Gradle and the JVM distribution)
+- GNU zip utilities (for packaging the native executable)
+- upx tool (executable in-place compression)
+
+The repository provides convenience scripts in `bin/` for local builds and installation into `~/bin`.
+
+Note: In this repository the scripts are named `bin/local_release` and `bin/local_jrelease`. In some environments these may be aliased as `bin/release` and `bin/jrelease`. The steps below use the actual file names present here.
+
+
+##### Option A: Native linuxX64 executable (`lyng`)
+
+1) Build the native binary:
+
+```
+./gradlew :lyng:linkReleaseExecutableLinuxX64
+```
+
+2) Install and package locally:
+
+```
+bin/local_release
+```
+
+What this does:
+- Copies the built executable to `~/bin/lyng` for easy use in your shell.
+- Produces `distributables/lyng-linuxX64.zip` containing the `lyng` executable.
+
+
+##### Option B: JVM distribution (`jlyng` launcher)
+
+This creates a JVM distribution with a launcher script and links it to `~/bin/jlyng`.
+
+```
+bin/local_jrelease
+```
+
+What this does:
+- Runs `./gradlew :lyng:installJvmDist` to build the JVM app distribution to `lyng/build/install/lyng-jvm`.
+- Copies the distribution under `~/bin/jlyng-jvm`.
+- Creates a symlink `~/bin/jlyng` pointing to the launcher script.
+
+
+#### Usage
+
+Once installed, ensure `~/bin` is on your `PATH`. You can then use either the native `lyng` or the JVM `jlyng` launcher (both have the same CLI surface).
+
+
+##### Running scripts
+
+- Run a script by file name and pass arguments to `ARGV`:
+
+```
+lyng path/to/script.lyng arg1 arg2
+```
+
+- Run a script whose name starts with `-` using `--` to stop option parsing:
+
+```
+lyng -- -my-script.lyng arg1 arg2
+```
+
+- Execute inline code with `-x/--execute` and pass positional args to `ARGV`:
+
+```
+lyng -x "println(\"Hello\")" more args
+```
+
+- Print version/help:
+
+```
+lyng --version
+lyng --help
+```
+
+### Use in shell scripts
+
+Standard unix shebangs (`#!`) are supported, so you can make Lyng scripts directly executable on Unix-like systems. For example:
+
+    #!/usr/bin/env lyng
+    println("Hello, world!")
+
+
+##### Formatting source: `fmt` subcommand
+
+Format Lyng files with the built-in formatter.
+
+Basic usage:
+
+```
+lyng fmt [OPTIONS] FILE...
+```
+
+Options:
+- `--check` — Check-only mode. Prints file paths that would change and exits with code 2 if any changes are needed, 0 otherwise.
+- `-i, --in-place` — Write formatted content back to the source files (off by default).
+- `--spacing` — Apply spacing normalization.
+- `--wrap`, `--wrapping` — Enable line wrapping.
+
+Semantics and exit codes:
+- Default behavior is to write formatted content to stdout. When multiple files are provided, the output is separated with `--- <path> ---` headers.
+- `--check` and `--in-place` are mutually exclusive; using both results in an error and exit code 1.
+- `--check` exits with 2 if any file would change, with 0 otherwise.
+- Other errors (e.g., I/O issues) result in a non-zero exit code.
+
+Examples:
+
+```
+# Print formatted content to stdout
+lyng fmt src/file.lyng
+
+# Format multiple files to stdout with headers
+lyng fmt src/a.lyng src/b.lyng
+
+# Check mode: list files that would change; exit 2 if changes are needed
+lyng fmt --check src/**/*.lyng
+
+# In-place formatting
+lyng fmt -i src/**/*.lyng
+
+# Enable spacing normalization and wrapping
+lyng fmt --spacing --wrap src/file.lyng
+```
+
+
+#### Notes
+
+- Both native and JVM distributions expose the same CLI interface. Use whichever best fits your environment.
+- When executing scripts, all positional arguments after the script name are available in Lyng as `ARGV`.
+- The interpreter recognizes shebang lines (`#!`) at the beginning of a script file and ignores them at runtime, so you can make Lyng scripts directly executable on Unix-like systems.