or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ast.mdbuild.mdcli.mdcodegen.mdcorefn.mddocs.mderrors.mdide.mdindex.mdinteractive.mdparser.mdsugar.mdtypes.md
tile.json

cli.mddocs/

Command Line Interface

The purs executable provides comprehensive commands for compiling PureScript projects, generating documentation, running IDE servers, and analyzing code structure.

Capabilities

Compile Command

Compiles PureScript source files to JavaScript with dependency resolution and incremental compilation support.

purs compile [FILES...] [OPTIONS]

# Core options:
--output, -o DIR          Output directory (default: output)
--comments               Include comments in generated code
--source-maps            Generate source maps
--verbose-errors, -v     Display verbose error messages
--json-errors            Error messages in JSON format
--censor-codes CODES     Suppress warnings by error code
--strict                 Treat warnings as errors
--no-prefix             Omit module path prefix from output files

Usage Examples:

# Compile all PureScript files in src/ and dependencies
purs compile "src/**/*.purs" "bower_components/*/src/**/*.purs"

# Compile with source maps and verbose errors
purs compile --source-maps --verbose-errors "src/**/*.purs"

# Compile with JSON error output for tooling
purs compile --json-errors "src/**/*.purs" 2> errors.json

Documentation Command

Generates documentation from PureScript source files in multiple formats with comprehensive API information.

purs docs [FILES...] [OPTIONS]

# Format options:
--format FORMAT          Output format: markdown (default), html, ctags, etags
--output, -o DIR         Output directory
--hierarchy-images       Generate GraphViz images for type class hierarchies
--compile-output DIR     Use pre-compiled output directory

Usage Examples:

# Generate Markdown documentation
purs docs "src/**/*.purs" --format markdown --output docs/

# Generate HTML documentation with hierarchy images
purs docs "src/**/*.purs" --format html --hierarchy-images

IDE Server Command

Starts or communicates with the IDE language server for editor integration providing completion, type information, and rebuilding.

purs ide server [OPTIONS]
purs ide client [OPTIONS]

# Server options:
--port, -p PORT          Port number (default: 4242)
--directory, -d DIR      Project root directory
--output-directory DIR   Compiled output directory
--log-level LEVEL        Log level: all, none (default), debug, perf
--polling               Use polling for file watching
--no-watch              Disable file watching

# Client options:  
--port, -p PORT          Server port

Usage Examples:

# Start IDE server on default port
purs ide server --directory .

# Start server with debug logging and custom port
purs ide server --port 8080 --log-level debug

# Query server for completions (client mode)
echo '{"command": "complete", "params": {"filters": [], "matcher": {"matcher": "flex", "params": {"search": "map"}}}}' | purs ide client

REPL Command

Starts the interactive PureScript REPL (PSCi) for expression evaluation and experimentation.

purs repl [FILES...] [OPTIONS]

# Options:
--port, -p PORT          PSCi server port
--node-path PATH         Path to Node.js executable
--node-opts OPTS         Additional Node.js options

Usage Examples:

# Start REPL with project sources loaded
purs repl "src/**/*.purs" "bower_components/*/src/**/*.purs"

# Start REPL with custom Node.js options
purs repl --node-opts="--max-old-space-size=4096"

Graph Command

Generates module dependency graphs for analyzing project structure and dependencies.

purs graph [FILES...] [OPTIONS]

# Options:
--json                   Output in JSON format

Usage Examples:

# Generate dependency graph in DOT format
purs graph "src/**/*.purs" > dependencies.dot

# Generate JSON format for programmatic processing
purs graph --json "src/**/*.purs" > dependencies.json

Hierarchy Command

Creates GraphViz directed graphs of PureScript type class hierarchies for visualization.

purs hierarchy [FILES...] [OPTIONS]

Usage Examples:

# Generate type class hierarchy graph
purs hierarchy "src/**/*.purs" > hierarchy.dot

# Convert to image with GraphViz
purs hierarchy "src/**/*.purs" | dot -Tpng > hierarchy.png

Publish Command

Prepares documentation packages for upload to Pursuit (the PureScript package registry).

purs publish [OPTIONS]

# Options:
--manifest FILE          Package manifest file
--resolutions FILE       Dependency resolutions file
--compile-output DIR     Compiled output directory

Usage Examples:

# Prepare documentation for Pursuit
purs publish --manifest psc-package.json

# Publish with custom output directory
purs publish --compile-output ./output

Global Options

Options available across all commands:

--help, -h               Show help information
--version                Show version number
--verbose, -v            Enable verbose output
--quiet, -q              Suppress output

Exit Codes

The purs command uses standard exit codes:

  • 0: Success
  • 1: Compilation errors or command failure
  • 2: Warning treated as error (with --strict)

File Patterns

Commands accept glob patterns for specifying input files:

# Single directory
"src/**/*.purs"

# Multiple directories
"src/**/*.purs" "test/**/*.purs" "bower_components/*/src/**/*.purs"

# Specific files
"src/Main.purs" "src/Utils.purs"

Output Structure

The compiled output directory contains:

output/
├── Main/                    # Module directories
│   ├── index.js            # Compiled JavaScript
│   ├── index.js.map        # Source map (if enabled)
│   └── externs.cbor        # Type information
├── Data.Array/
│   ├── index.js
│   └── externs.cbor
└── ...

Integration with Build Tools

Common integration patterns:

# npm scripts (package.json)
{
  "scripts": {
    "build": "purs compile \"src/**/*.purs\" \"bower_components/*/src/**/*.purs\"",
    "watch": "purs compile --watch \"src/**/*.purs\"",
    "docs": "purs docs \"src/**/*.purs\" --format html"
  }
}

# Make target
build:
	purs compile "src/**/*.purs" "bower_components/*/src/**/*.purs"

# Pulp integration (legacy build tool)
pulp build
pulp docs