cls.json Reference: CLS Project Manifest Fields and Defaults

Every CLS project is driven by a single cls.json file at the project root. This manifest is the authoritative source of truth for the entire toolchain: clx run reads it to locate the entry point, clx build uses it to select the compiler target and optimization level, clx check applies its type-checking rules, and clx install resolves dependencies against the declared registry. You never need to pass repetitive flags on the command line — all defaults live here and are applied automatically.

Annotated example

The following is a complete cls.json that exercises every section. All fields not present default to the values described in the reference below.

{
  "name": "test-config",
  "version": "0.1.0",
  "description": "Test de configuracion",
  "authors": ["test"],
  "license": "MIT",
  "registry": "https://registry.cls-lang.org",
  "entry": "examples/test-config.clsx",

  "project": {
    "sourceDir": "src",
    "outDir": "dist",
    "target": "executable"
  },

  "compiler": {
    "targetArchitecture": "wasm",
    "optimizationLevel": "O2",
    "sourceMaps": true,
    "types": {
      "check": true,
      "strict": false,
      "noImplicitAny": false,
      "nullSafety": true
    },
    "features": {
      "async": false,
      "macros": false,
      "experimental": false
    },
    "warnings": {
      "unusedVariables": "warn",
      "deadCode": "warn",
      "treatWarningsAsErrors": false
    }
  },

  "interpreter": {
    "optimization": false,
    "mode": "pure-ast",
    "runtime": {
      "memoryLimit": "512MB",
      "stackSize": "8MB",
      "gc": {
        "enabled": false,
        "strategy": "compiled",
        "threshold": "64MB"
      }
    },
    "sandbox": {
      "allowFs": true,
      "allowNet": false,
      "maxExecutionTime": 5000
    }
  },

  "dependencies": {},
  "devDependencies": {}
}

Metadata fields

These top-level fields identify the project and tell the toolchain where to start execution.

name

string

required

The unique name of the project. Used as the package identifier when publishing to a registry, and embedded into .clsapp bundles as the application name. Must not contain spaces.

version

string

default:"0.1.0"

A semver version string for the project. Embedded into compiled .clsapp bundles by clx build. Increment this before publishing a new release.

description

string

default:"\"\""

A short, human-readable description of the project. Shown in registry listings.

authors

string[]

default:"[]"

An ordered list of author names or email addresses, e.g. ["Alice <alice@example.com>"]. Informational only.

license

string

default:"\"MIT\""

An SPDX license identifier, e.g. "MIT", "Apache-2.0", or "GPL-3.0-only". Used when publishing packages to the registry.

registry

string

default:"\"https://registry.cls-lang.org\""

The base URL of the package registry used by clx add and clx install. Override this to point at a private or self-hosted registry.

entry

string

default:"\"src/main.clsx\""

Path to the main .clsx source file, relative to the project root. clx run and clx build use this path when no file argument is supplied on the command line.

`project` object

The project block controls source layout and the kind of artifact clx build produces.

project.sourceDir

string

default:"\"src\""

The directory that contains all CLS source files. clx check scans this directory recursively when no path argument is given.

project.outDir

string

default:"\"dist\""

The directory where clx build writes its output (.clsapp, .clslib, or .clsbin files). Created automatically if it does not exist.

project.target

"executable" | "library" | "dynamic-lib"

default:"\"executable\""

The type of artifact to produce:

"executable" — a standalone .clsapp bundle runnable with clxr.
"library" — a static .clslib that other projects can import.
"dynamic-lib" — a dynamically loadable .clslib loaded at runtime via Lib.load().

`compiler` object

The compiler block configures the CLS compiler invoked by clx build and clx check.

compiler.targetArchitecture

"wasm" | "x86_64" | "arm64" | "bytecode"

default:"\"wasm\""

The machine or bytecode target for compiled output:

"wasm" — WebAssembly (default, broadest compatibility).
"x86_64" — native 64-bit x86 binary.
"arm64" — native ARM64 binary (Apple Silicon, Raspberry Pi, etc.).
"bytecode" — CLS portable bytecode, interpreted by clxr without native compilation.

compiler.optimizationLevel

"O0" | "O1" | "O2" | "O3" | "Os"

default:"\"O2\""

Controls the trade-off between compilation speed and runtime performance:

"O0" — no optimization; fastest compile, slowest output. Best for debugging.
"O1" — basic optimizations.
"O2" — standard optimizations (recommended default).
"O3" — aggressive optimizations; may significantly increase compile time.
"Os" — optimize for output size rather than speed; useful for .clsapp distribution.

compiler.sourceMaps

boolean

default:"true"

When true, the compiler emits source map files alongside the compiled output. Source maps let debuggers and error reporters display original .clsx line numbers instead of internal offsets.

`compiler.types`

The types sub-object controls how strictly the CLS type checker enforces annotations.

compiler.types.check

boolean

default:"true"

Enables the type checker. When true, CLS operates in hybrid mode — typed and untyped code can coexist. Set to false to run fully dynamically typed (no type errors at compile time).

compiler.types.strict

boolean

default:"false"

Enables strict typing mode. Requires explicit type annotations on all function parameters and return values. Only meaningful when check is true.

compiler.types.noImplicitAny

boolean

default:"false"

When true, the compiler rejects any binding whose type cannot be inferred and would otherwise default to any. Forces explicit annotation. Only meaningful when check is true.

compiler.types.nullSafety

boolean

default:"true"

When true, the compiler tracks nullability and prevents null pointer exceptions by requiring explicit null checks before dereferencing nullable values.

`compiler.features`

Feature flags enable language capabilities that are opt-in, experimental, or have a compile-time cost.

compiler.features.async

boolean

default:"false"

Enables async/await syntax and the async runtime. Required for any code that uses asynchronous I/O or concurrent tasks.

compiler.features.macros

boolean

default:"false"

Enables the CLS macro system, which allows compile-time code generation and metaprogramming via macro definitions.

compiler.features.experimental

boolean

default:"false"

Unlocks language features that are still under active development and may change or be removed in future versions. Use only in non-production projects.

`compiler.warnings`

Controls which issues the compiler surfaces as warnings and how they are treated.

compiler.warnings.unusedVariables

"warn" | "error" | "off"

default:"\"warn\""

What to do when a declared variable is never read:

"warn" — emit a compiler warning (default).
"error" — treat as a compile error and abort.
"off" — silently ignore unused variables.

compiler.warnings.deadCode

"warn" | "error" | "off"

default:"\"warn\""

What to do when the compiler detects unreachable code paths. Accepts the same values as unusedVariables.

compiler.warnings.treatWarningsAsErrors

boolean

default:"false"

When true, any compiler warning is promoted to a hard error, causing the build to fail. Useful in CI pipelines to enforce zero-warning policies.

`interpreter` object

The interpreter block configures the runtime used by clx run (and clxr) when executing CLS programs without full ahead-of-time compilation.

interpreter.optimization

boolean

default:"false"

When true, the interpreter applies optimizations to the AST before execution, trading startup time for faster steady-state performance. Useful for long-running programs run via clx run.

interpreter.mode

"pure-ast" | "jit"

default:"\"pure-ast\""

The execution strategy:

"pure-ast" — the interpreter walks the parsed AST directly. No code generation, lowest startup latency.
"jit" — just-in-time compilation of hot paths (reserved for future releases).

`interpreter.runtime`

Memory limits and garbage collection settings for the interpreter runtime.

interpreter.runtime.memoryLimit

string

default:"\"512MB\""

Maximum heap memory the interpreter may allocate, expressed as a string with a unit suffix (KB, MB, GB). Programs that exceed this limit are terminated with an out-of-memory error.

interpreter.runtime.stackSize

string

default:"\"8MB\""

Maximum call-stack depth expressed as a memory size. Deep recursive programs may require increasing this value. Accepts the same unit suffixes as memoryLimit.

`interpreter.runtime.gc`

Controls garbage collection behavior inside the interpreter.

interpreter.runtime.gc.enabled

boolean

default:"false"

Enables the garbage collector. When false, memory is managed by reference counting without a tracing GC cycle. Enable for programs that create long-lived object graphs with cycles.

interpreter.runtime.gc.strategy

"active" | "compiled"

default:"\"compiled\""

Selects the GC strategy:

"active" — a runtime GC runs concurrently during program execution.
"compiled" — GC logic is baked into the compiled WASM output rather than running as a separate pass. Only relevant when targetArchitecture is "wasm".

interpreter.runtime.gc.threshold

string

default:"\"64MB\""

The heap size at which the GC triggers a collection cycle. Accepts the same unit suffixes as memoryLimit. Only meaningful when gc.enabled is true.

`interpreter.sandbox`

Sandbox settings restrict what the interpreter is allowed to access at runtime. All permissions default to denied for security.

interpreter.sandbox.allowFs

boolean

default:"false"

Grants the program access to the Virtual File System (VFS). When false, any attempt to use the fs module raises a runtime permission error. See VFS for details on protocol URIs and path sandboxing.

interpreter.sandbox.allowNet

boolean

default:"false"

Grants the program access to network APIs (HTTP, TCP, UDP). When false, all outbound connections are blocked at the runtime level.

interpreter.sandbox.maxExecutionTime

integer

default:"5000"

Maximum wall-clock time, in milliseconds, that the interpreter allows the program to run before forcibly terminating it. Set to 0 to disable the timeout entirely.

`dependencies` and `devDependencies`

CLS packages are declared as key/value maps where the key is the package name on the registry and the value is a semver range.

{
  "dependencies": {
    "http-server": "^1.0.0",
    "json-utils": "~0.2.0"
  },
  "devDependencies": {
    "test-runner": "^0.5.0"
  }
}

dependencies — packages required at runtime by the compiled or interpreted program.
devDependencies — packages used only during development (test runners, linters, code generators). They are never bundled into .clsapp output.

Common version range operators:

Operator	Meaning	Example
`^`	Compatible with (patch + minor updates allowed)	`^1.0.0` → `>=1.0.0 <2.0.0`
`~`	Approximately equivalent (patch updates only)	`~0.2.0` → `>=0.2.0 <0.3.0`
`=`	Exact version	`=1.2.3`

Working with dependencies:

clx add http-server

Run clx install after cloning a project or pulling changes that modify cls.json. The command reads cls.lock (if present) to guarantee reproducible installs.

`cls.lock` lockfile

cls.lock is generated automatically by clx install in the project root. It pins every dependency to an exact resolved version, ensuring that all developers and CI environments install identical package trees regardless of when they run clx install.

{
  "lockfileVersion": 1,
  "registry": "https://registry.cls-lang.org",
  "packages": {
    "http-server": { "version": "1.0.0" },
    "json-utils": { "version": "0.2.0" }
  }
}

Field	Description
`lockfileVersion`	Format version. Always `1` in the current toolchain.
`registry`	The registry URL used when this lockfile was generated.
`packages`	Map of package name → exact installed version.

Commit cls.lock to version control. Never edit it by hand — always let clx install regenerate it. Deleting the lockfile and re-running clx install will re-resolve all ranges to their latest compatible versions.

Common usage examples

clx new my-app
# Generates: cls.json  src/main.clsx  .gitignore

Introduction

CLI Reference

Project Configuration

cls.json Reference: CLS Project Manifest Fields and Defaults

Annotated example

Metadata fields

`project` object

`compiler` object

`compiler.types`

`compiler.features`

`compiler.warnings`

`interpreter` object

`interpreter.runtime`

`interpreter.runtime.gc`

`interpreter.sandbox`

`dependencies` and `devDependencies`

`cls.lock` lockfile

Common usage examples

Build docs developers (and LLMs) love

Introduction

CLI Reference

Project Configuration

Documentation Index

​Annotated example

​Metadata fields

​project object

​compiler object

​compiler.types

​compiler.features

​compiler.warnings

​interpreter object

​interpreter.runtime

​interpreter.runtime.gc

​interpreter.sandbox

​dependencies and devDependencies

​cls.lock lockfile

​Common usage examples

Build docs developers (and LLMs) love

Annotated example

Metadata fields

`project` object

`compiler` object

`compiler.types`

`compiler.features`

`compiler.warnings`

`interpreter` object

`interpreter.runtime`

`interpreter.runtime.gc`

`interpreter.sandbox`

`dependencies` and `devDependencies`

`cls.lock` lockfile

Common usage examples