CLI

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

Quick Reference

Command	Description
purus build [file]	Compile Purus files to JavaScript
purus run [file]	Compile and run without generating files
purus check <file>	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 --directory src

# Specify output directory
purus build --directory src --output 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
--directory <dir>	-d	Compile all Purus files in the directory
--output <dir>	-o	Specify output directory (overrides config.purus)
--no-header		Omit the // Generated by Purus header comment
--stdout		Print compiled JavaScript to stdout instead of writing files

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 -d 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 --directory src

Using config.purus

# Uses entry from config.purus
purus run

Options

Option	Alias	Description
--directory <dir>	-d	Run all Purus files in the directory

---

purus check

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

purus check hello.purus
# OK: hello.purus

---

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
# purus v0.2.1

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 header be true

-- Linter settings
const lint.no-var be ///warn///
const lint.indent-size be 2
const lint.max-line-length be ///off///

Build settings

Key	Type	Default	Description
entry	string	"src"	Source directory
output	string	"dist"	Output directory
header	boolean	true	Include // Generated by Purus header comment

Linter settings

Key	Type	Default	Description
lint.no-var	string	"warn"	"warn" or "error" on var usage
lint.indent-size	number	2	Expected indentation size
lint.max-line-length	string/number	"off"	Maximum line length ("off" to disable)

How config.purus is used

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

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

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

---

Programmatic API

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

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

compile(source, options?)

Compile Purus source code to JavaScript.

const js = compile("const x be 42");
// => "// Generated by Purus 0.2.1\nconst x = 42;\n"

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

Option	Type	Default	Description
header	boolean	true	Include header comment

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);  // => "0.2.1"