Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/elfrask/cls/llms.txt

Use this file to discover all available pages before exploring further.

clxr is the lightweight CLS runtime executor. Unlike clx, which ships the full development toolchain (type checker, LSP server, package manager, REPL, and more), clxr contains only what is needed to run a CLS program: the lexer, parser, tree-walker interpreter, and the core standard library. It is designed for deployment scenarios where you want to ship a .clsapp package or a standalone .clsx script and execute it on a target machine without installing the development tools.

​
Usage

clxr <file.clsx|app.clsapp>
clxr accepts exactly one positional argument: the path to either a CLS source file (.clsx) or a packaged application (.clsapp). Any additional arguments after the file path are collected and forwarded to the program’s main(args: String[]) function. 
# Run a source file directly
clxr script.clsx

# Run a packaged application
clxr app.clsapp

# Pass arguments to main()
clxr app.clsapp --port 8080

​
Execution Modes

​
Running a .clsx Source File

When the argument ends in .clsx, clxr reads the file from disk and immediately compiles and executes it through the full pipeline:
1

Lex

The source text is tokenized by the Lexer. Syntax errors are reported with source context and clxr exits with code 1.
2

Parse

The token stream is parsed into an AST by the Parser. Parse errors are reported the same way.
3

Execute module body

The interpreter walks the AST and evaluates all top-level statements (variable declarations, function definitions, etc.).
4

Call main()

After the module body completes, clxr looks for a main function and calls it, forwarding any command-line arguments. The integer return value of main becomes the process exit code.
clxr hello.clsx

function main(args: String[]) -> int {
    print("Hello from clxr!");
    return 0;
};

​
Running a .clsapp Packaged Application

A .clsapp file is a ZIP archive produced by clx build. When the argument ends in .clsapp, clxr mounts the archive through the Virtual File System (VFS) before executing:
1

Open the ZIP

clxr opens the .clsapp archive and registers its contents under the res:// VFS protocol, making all bundled resources accessible at runtime via res://filename.
2

Read manifest.json

clxr reads manifest.json from the archive to determine the entry point file name. If no manifest is present, it defaults to source.clsx.
3

Extract and compile the entry point

The entry source file is read from the ZIP, then lexed and parsed in memory — no temporary files are created on disk.
4

Execute

The interpreter executes the module body and then calls main(), exactly as in the direct .clsx flow.
clxr app.clsapp
The manifest.json inside the archive follows this structure: 
{
  "name": "my-app",
  "version": "1.0.0",
  "entry": "source.clsx",
  "format": "source"
}
Resources bundled inside a .clsapp (images, config files, data) are accessible at res:// paths. However, clxr does not expose the fs module, so reading from the host filesystem is not available. Use res:// for embedded assets.

​
Available Modules

clxr initialises the interpreter with ModuleResolver::with_core_stdlib(), which includes only the cross-platform core modules. The desktop-only node modules (fs, http, Lib) are not registered.
ModuleAvailable in clxrNotes
math✅math.sqrt, math.pow, math.random, etc.
json✅json.parse, json.stringify
async✅async/await support
fs❌Desktop-only — use clx run instead
http❌Desktop-only — use clx run instead
Lib❌Desktop-only .clslib loader — use clx run instead
All intrinsic functions (print, input, len, type, int, float, str, bool, now, exit, sleep, throw) are always available without any import.
If your script imports fs or http, clxr will fail at runtime with a module-not-found error. Use clx run during development, and only use clxr for scripts or applications that rely solely on the core stdlib.

​
Error Reporting

When a runtime error occurs, clxr builds a full call stack traceback and prints it before exiting with code 1. Each frame in the traceback includes:
  • A frame number
  • The function name and source file
  • The offending source line with a ^ caret marking the exact position
Runtime Error: division by zero

  at divide (src/math.clsx:5:14)
    5 |     return a / b;
      |              ^
  at main (src/main.clsx:12:5)
   12 |     var result = divide(10, 0);
      |     ^
Syntax errors (detected during lexing or parsing) are also reported with source context before the interpreter starts.

​
Comparison: clx vs clxr

Featureclxclxr
Primary purposeDevelopment & authoringDeployment & execution
Core stdlib (math, json, async)✅✅
Desktop modules (fs, http, Lib)✅❌
Type checker (clx check)✅❌
REPL (clx repl)✅❌
LSP server (clx lsp)✅❌
Project scaffolding (clx new)✅❌
Package manager (clx add/install)✅❌
Build to .clsapp (clx build)✅❌
Run .clsx directly✅✅
Run .clsapp packages❌✅
Full call stack traceback✅✅
Binary sizeFull toolchainLightweight

​
Exit Codes

CodeMeaning
0main() returned 0 — successful execution
1Syntax error, parse error, runtime error, or the file could not be opened
The exit code is taken directly from the integer value returned by your program’s main function, so you can signal specific outcomes to the calling shell: 
function main(args: String[]) -> int {
    if (len(args) < 1) {
        print("Usage: app.clsapp <name>");
        return 2;
    };
    print("Hello,", args[0]);
    return 0;
};

clxr app.clsapp
echo $?   # 2

clx build

Package your project into a .clsapp file

clx Reference

Full development CLI reference

Build docs developers (and LLMs) love

Get started for freeTalk to us