CLI

The Purus CLI provides commands for compiling, running, checking, and managing Purus projects.

Quick Reference

Command	Description
purus build [file|dir]	Compile Purus files to JavaScript
purus run [file|dir]	Compile and run without generating files
purus check [file|dir]	Syntax check only
purus new [name]	Create a new project
purus init	Initialize project in current directory
purus version	Show version
purus help	Show help

Aliases: compile = build, create = new

Commands

purus build / purus compile

Compile Purus source files to JavaScript. Supports single file, directory, and config-based compilation.

Single file

purus build hello.purus
# Output: hello.js

purus build app.cpurus
# Output: app.cjs

purus build lib.mpurus
# Output: lib.mjs

Extension	Output	Format
.purus	.js	Standard JavaScript
.cpurus	.cjs	CommonJS module
.mpurus	.mjs	ES Module

Directory

Compile all .purus, .cpurus, and .mpurus files in a directory. The output directory structure mirrors the source.

# Compile all files in src/ to dist/
purus build src

# Specify output directory
purus build src --output build

# Using --entry flag
purus build --entry src
purus build -e src -o build

Using config.purus

When no file or directory is specified, Purus reads config.purus from the current or parent directory.

# Uses entry and output from config.purus
purus build

See config.purus for configuration details.

Options

Option	Alias	Description
--entry <file|dir>	-e	Specify entry file or directory
--output <dir>	-o	Specify output directory (overrides config.purus)
--no-header		Omit the // Generated by Purus header comment
--strict [true|false]		Enable/disable strict mode (default: true)
--type <type>	-t	Set module type: module (ESM) or commonjs (CJS)
--stdout		Print compiled JavaScript to stdout instead of writing files

You can also pass a file or directory as a positional argument instead of using --entry.

Examples

# Compile without header comment
purus build --no-header hello.purus

# Print compiled output to stdout
purus build --stdout hello.purus

# Compile directory with custom output
purus build src -o build

# Using --entry flag
purus build -e src -o build

# Compile with config, override output directory
purus build --output public/js

---

purus run

Compile and run Purus files without generating output files. Useful for quick testing and development.

Single file

purus run hello.purus

Directory

Run all Purus files in a directory:

purus run src

# Using --entry flag
purus run --entry src
purus run -e src

Using config.purus

# Uses entry from config.purus
purus run

Options

Option	Alias	Description
--entry <file|dir>	-e	Specify entry file or directory
--strict [true|false]		Enable/disable strict mode (default: true)

You can also pass a file or directory as a positional argument instead of using --entry.

---

purus check

Check Purus source code for syntax errors without compiling. Prints OK: <file> if the syntax is valid.

Single file

purus check hello.purus
# OK: hello.purus

Directory

Check all Purus files in a directory:

purus check src

# Using --entry flag
purus check --entry src
purus check -e src

Using config.purus

# Uses entry from config.purus
purus check

Options

Option	Alias	Description
--entry <file|dir>	-e	Specify entry file or directory

You can also pass a file or directory as a positional argument instead of using --entry.

---

purus new / purus create

Create a new Purus project with an interactive setup. The target directory must not exist or must be empty.

# Interactive setup
purus new my-project

# Skip all prompts
purus new my-project -y

What it creates

File	Description
src/main.purus	Entry point with Hello World example
config.purus	Build and lint configuration
.prettierrc	Prettier configuration for Purus
README.md	Project README with scripts reference
.gitignore	Git ignore rules
package.json	npm package with scripts

package.json scripts

Script	Command	Description
purus	purus	Run purus CLI
build	purus build	Compile project
compile	purus compile	Compile project (alias)
exec	purus run	Run project
format	prettier --write ./src	Format source files
lint	purus-lint	Lint source files

Optional devDependencies

When prompted (or with -y), the following packages are installed:

• purus — Compiler
• @puruslang/linter — Linter
• @puruslang/prettier-plugin-purus — Prettier plugin
• prettier — Code formatter

---

purus init

Initialize a Purus project in the current directory. Creates src/ and src/main.purus if they don’t exist.

purus init

---

purus version

Display the installed Purus version.

purus version

Output: Purus v ...

Aliases: purus --version, purus -v

---

purus help

Display the help message with all available commands.

purus help

Aliases: purus --help, purus -h

---

config.purus

Place a config.purus file in your project root to configure build, run, and lint settings. The file uses Purus syntax itself.

-- Purus Configuration
const entry be ///src///
const output be ///dist///
const type be ///module///
const header be true
const strict be true

-- Linter settings
const lint.no-var be ///warn///
const lint.no-nil be ///off///
const lint.indent-size be 2
const lint.max-line-length be ///off///
const lint.no-trailing-whitespace be ///warn///
const lint.no-unused-import be ///warn///
const lint.consistent-naming be ///off///

Build settings

Key	Type	Default	Description
entry	string	"src"	Source directory
output	string	"dist"	Output directory
type	string	"module"	Module type: "module" (ESM) or "commonjs" (CJS)
header	boolean	true	Include // Generated by Purus header comment
strict	boolean	true	Enable strict mode ("use strict" at top of output)

Linter settings

Key	Type	Default	Description
lint.no-var	string	"warn"	"warn" or "error" on var usage
lint.no-nil	string	"off"	"warn" or "error" on nil usage
lint.indent-size	number	2	Expected indentation size
lint.max-line-length	string/number	"off"	Maximum line length ("off" to disable)
lint.no-trailing-whitespace	string	"warn"	"warn" or "error" on trailing whitespace
lint.no-unused-import	string	"warn"	"warn" or "error" on unused imports
lint.consistent-naming	string	"off"	"warn" or "error" for naming convention checks

How config.purus is used

The following commands read config.purus automatically when no file arguments are given:

• purus build — Uses entry, output, type, header, and strict settings
• purus run — Uses entry setting
• purus check — Uses entry setting
• purus-lint — Uses lint.* settings and entry for file discovery

Command-line options (e.g. --output, --entry) override config values.

---

Programmatic API

Purus can also be used as a Node.js library.

const { compile, check, version } = require("purus");

TypeScript Support

Purus ships with built-in TypeScript type definitions. No additional @types package is needed.

import { compile, check, version } from "purus";

const js: string = compile("const x be 42", { header: false, strict: true, type: "module" });
const valid: true = check("const x be 42");
console.log(version); // string

compile(source, options?)

Compile Purus source code to JavaScript.

The header comment includes the installed Purus version (currently ... ):

const js = compile("const x be 42");
// => "// Generated by Purus x.y.z\n\"use strict\";\nconst x = 42;\n"

const js = compile("const x be 42", { header: false });
// => "\"use strict\";\nconst x = 42;\n"

Option	Type	Default	Description
header	boolean	true	Include header comment
strict	boolean	true	Enable strict mode ("use strict" at top of output)
type	string	"module"	Module type: "module" (ESM) or "commonjs" (CJS)

check(source)

Check Purus source code for syntax errors. Returns true if valid, throws an error otherwise.

check("const x be 42");    // => true
check("const x be");        // throws Error

version

The current Purus version string: ...

console.log(version);  // => "x.y.z"