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.

clx is the full development toolchain for the CLS programming language. It handles everything you need during development: creating projects, running scripts, type-checking, packaging, launching a language server for editor integration, and managing dependencies. Use clx when you are writing, debugging, or building CLS code. For deploying or distributing a finished application without the development toolchain overhead, use clxr instead.

​
Global Flags

These flags are accepted by clx itself, before any subcommand.
FlagDescription
-h, --helpPrint the help message and exit
-v, --versionPrint the clx version string and exit
--quietSuppress log output
clx --version
# clx 2.0.0
# CLS Language Compiler & Runtime

​
Project Management

​
clx new

clx new is the recommended way to start every CLS project. It creates a well-formed directory layout and a valid cls.json manifest that all other subcommands rely on.
Syntax 
clx new <name> [--lib]
Creates a new CLS project directory at <name>/ containing:
  • cls.json — project manifest with name, version, entry point, and dependency fields pre-filled
  • src/main.clsx — a minimal main entry point (omitted for library targets)
  • modules/ — empty directory reserved for installed dependencies
  • .gitignore — pre-configured to ignore modules/, dist/, and .cls-types/
FlagDescription
--libCreate a library project; no src/main.clsx is generated and project.target is set to "library"
Examples 
# Create an executable project
clx new my-app

# Create a reusable library
clx new my-lib --lib
After running clx new my-app the generated src/main.clsx looks like: 
function main(args: String[]) -> int {
    print("Hello from CLS!");
    return 0;
}

​
Development

​
clx run

Syntax 
clx run [file] [-- args]
Lexes, parses, and executes a CLS source file using the tree-walker interpreter. If no file argument is given, clx run reads the entry field from cls.json in the current directory and falls back through the candidate list main.clsx → src/main.clsx → mod.clsx → src/mod.clsx until a file is found. Everything after the -- separator is collected and passed to the program’s main(args: String[]) function. During execution the following modules are available in addition to the core stdlib (math, json, async): fs, http, and Lib (desktop node modules). Examples 
# Run the project entry point defined in cls.json
clx run

# Run a specific file
clx run src/main.clsx

# Pass arguments to main()
clx run src/main.clsx -- --port 8080 --debug

​
clx check

Syntax 
clx check [file|dir] [--strict]
Runs the CLS type checker without executing any code. Accepts a single .clsx file or a directory path. When given a directory, clx check recursively scans all .clsx files, skipping hidden directories and the modules/, dist/, and libs/ folders. For each file, clx check resolves imports recursively and registers their exported types as a prelude so that cross-file type references (e.g. a struct defined in another module) are correctly validated. Diagnostics are printed with severity, message, source location, the offending source line, and a ^ caret pointing to the exact column.
FlagDescription
--strictEnable strict mode — incompatible assignments become hard errors instead of warnings
Examples 
# Check a single file
clx check src/main.clsx

# Check all .clsx files in the project
clx check .

# Strict mode (errors on any type mismatch)
clx check src/ --strict
Running clx check with no arguments checks the current directory. Pipe the output to a file or CI log — exit code 1 means at least one error was found.

​
clx repl

Syntax 
clx repl
Starts an interactive Read-Eval-Print Loop. Expressions are evaluated and their result is printed immediately. Statements (var, function, for, etc.) are executed and their bindings persist for the rest of the session. Type :salir, :q, or :exit to quit, or press Ctrl+C. Type :help to see the list of REPL commands. Example 
clx repl
# CLS 2.0 REPL (Ctrl+C o :salir para salir)

> var x = 40 + 2
> x
42
> function greet(name: String) { print("Hello,", name); };
> greet("world")
Hello, world
> :salir

​
Compilation

​
clx build

Syntax 
clx build [file] [-o <out>]
Verifies that the source compiles and packages it into a .clsapp file. A .clsapp is a ZIP archive containing:
  • manifest.json — application metadata (name, version, entry, format)
  • source.clsx — the source file
If no file is provided, the entry field from cls.json is used. The default output path is dist/app.clsapp; the output directory is created automatically. The resulting .clsapp can be executed directly with clxr.
FlagDescription
-o <out>Output path for the .clsapp file (default: dist/app.clsapp)
--out <out>Long form of -o
Examples 
# Build using cls.json entry, output to dist/app.clsapp
clx build

# Build a specific file
clx build src/main.clsx

# Build with a custom output path
clx build src/main.clsx -o release/myapp.clsapp

​
Language Server

​
clx lsp

Syntax 
clx lsp [--tcp <addr>] [--silent]
Starts the CLS Language Server Protocol (LSP) server. By default the server communicates over stdin/stdout, which is the mode used by the VS Code extension and most editors. The LSP server provides:
  • Real-time diagnostics (syntax errors and type errors)
  • Autocompletion (keywords, intrinsics, modules, in-scope symbols)
  • Hover documentation
  • Go-to-definition for functions and variables
  • Document symbols list
FlagDescription
--tcp <addr>Listen on a TCP address instead of stdin/stdout (e.g. 127.0.0.1:9876)
--silent / -sSuppress the [clx lsp] ready startup message
Examples 
# Start LSP on stdin/stdout (default — used by editors)
clx lsp

# Start LSP on a TCP socket
clx lsp --tcp 127.0.0.1:9876

# Suppress startup message
clx lsp --silent
Most editors connect to clx lsp automatically when you install the CLS extension. You only need to run it manually when testing or debugging the LSP connection.

​
Inspection & Types

​
clx ast

Syntax 
clx ast <file> [--json]
Parses a .clsx source file and dumps the resulting Abstract Syntax Tree (AST) to stdout. Without --json the output is Rust’s debug ({:#?}) representation, suitable for quick inspection. With --json it uses the JSON backend and emits structured JSON, which is easier to process programmatically.
FlagDescription
--jsonEmit the AST as JSON instead of debug text
Examples 
# Debug text dump
clx ast src/main.clsx

# Machine-readable JSON
clx ast src/main.clsx --json

# Pipe JSON AST into jq for querying
clx ast src/main.clsx --json | jq '.statements[0]'

​
clx maptype

Syntax 
clx maptype [path] -o <dir> [--watch|-w]
Generates .type.json type-map files from .clsx and .clsi source files. Type maps describe all declarations in a file — functions (with signatures, parameter types, return types, and doc-comment metadata), variables, constants, structures, classes, interfaces, modules, namespaces, and imports. They are consumed by the VS Code extension to power autocompletion. When path is a directory, clx maptype processes all .clsx / .clsi files recursively, preserving the source directory structure inside the output directory. When path is a single file, one .type.json file is written. The default output directory is .cls-types.
FlagDescription
-o <dir>Output directory for .type.json files (default: ./.cls-types)
--out <dir>Long form of -o
--watch / -wWatch mode — polls for changes every 2 seconds and regenerates modified files automatically
Examples 
# Generate type maps for the whole project
clx maptype . -o .cls-types

# Generate for a single file
clx maptype src/utils.clsx -o .cls-types

# Watch mode for continuous editor feedback
clx maptype . -o .cls-types --watch
Add .cls-types to your .gitignore — type maps are generated artifacts, not source files.
The generated .type.json format looks like: 
{
  "source": "src/utils.clsx",
  "entries": [
    {
      "name": "add",
      "kind": "function",
      "line": 1,
      "col": 1,
      "signature": "add(a: int, b: int) -> int",
      "params": [
        { "name": "a", "type_": "int", "doc": null },
        { "name": "b", "type_": "int", "doc": null }
      ],
      "return_type": "int",
      "doc": ""
    }
  ]
}

​
Package Management

​
clx add

Syntax 
clx add <pkg> [--dev]
Adds a dependency entry to cls.json. The package is recorded with the version constraint ^1.0.0. Run clx install afterward to actually download the package into modules/. Requires a cls.json in the current directory. Create one first with clx new.
FlagDescription
--devRecord the package under devDependencies instead of dependencies
Examples 
# Add a runtime dependency
clx add cls-colors

# Add a development-only dependency
clx add cls-test --dev

​
clx remove / clx rm

Syntax 
clx remove <pkg>
clx rm <pkg>
Removes a dependency from both dependencies and devDependencies in cls.json. Both remove and rm are equivalent aliases. Returns exit code 1 if the package is not found in either section. Example 
clx remove cls-colors
# or
clx rm cls-colors

​
clx install / clx i

Syntax 
clx install
clx i
Downloads all packages listed in dependencies and devDependencies from the registry and places them in the modules/ directory. After installation, a cls.lock lockfile is written recording the registry URL and resolved package versions. The registry URL is resolved in this priority order:
  1. CLS_REGISTRY environment variable
  2. registry field in cls.json
  3. Default: https://registry.cls-lang.org
Both install and i are equivalent aliases. Example 
clx install
# Instalando desde: https://registry.cls-lang.org
#
#   cls-colors ... ✅ (1024 bytes)
#   cls-test   ... ✅ (2048 bytes)
#
# Instalación completada

Quickstart

Create your first CLS project end-to-end

clxr Reference

Deploy and run packaged .clsapp files

​
Exit Codes

CodeMeaning
0Success — no errors
1Error — compilation failure, type error, missing file, or invalid arguments

Build docs developers (and LLMs) love

Get started for freeTalk to us