Usage

Overview

The Soul CLI provides a comprehensive set of commands for developing, building, and managing Soul applications. This guide covers all available commands and their usage.

Global Flags

These flags can be used with any Soul command:

soul [command] --directory /path/to/project  # Set custom working directory
soul [command] --config config.json         # Use custom configuration file

Core Commands

`soul run` - Execute Soul Programs

Run Soul source code directly without compilation:

soul run app.soul
soul run --skip-validation app.soul # Skip dependency validation

Run Command Details

Features:

Executes Soul programs immediately without creating binaries
Auto-installs missing packages by scanning imports
Validates that exactly one genesis() function exists
Creates temporary executable for execution
Supports path aliases defined in soul.json

Requirements:

Must have exactly one genesis() function with no parameters
All dependencies must be available or auto-installable

`soul build` - Compile Soul Programs

Compile Soul source code into standalone executables:

soul build app.soul                  # Creates 'app' executable
soul build --skip-validation app.soul

Build Command Details

Features:

Creates self-contained executable binaries
Embeds source code in the executable
Auto-installs missing packages before compilation
Validates package dependencies
Output binary has same name as source file (without extension)

Output:

Standalone executable that doesn’t require Soul runtime
Can be distributed and run on systems without Soul installed

Version Management

`soul version` - Check Version

Display the current Soul version:

soul version
# Output: Soul 1.0.0

`soul update` - Update Soul

Update Soul to the latest version:

soul update              # Check and install updates
soul update --dry-run    # Check for updates without installing
soul update -n           # Same as --dry-run

Update Process

How it works:

Fetches latest version from GitHub releases
Downloads platform-specific archive (macOS, Linux, Windows)
Extracts and replaces current Soul binary
Automatically handles ARM64 and AMD64 architectures
Creates backup and rolls back on failure

Package Management

Soul includes a comprehensive package management system accessed through the pkg subcommands.

`soul pkg init` - Initialize Package

Create a new Soul package with soul.json manifest:

soul pkg init

This creates a soul.json file with:

{
  "name": "project-name",
  "version": "1.0.0",
  "description": "A Soul project",
  "license": "MIT",
  "scripts": {},
  "dependencies": {}
}

`soul pkg install` - Install Dependencies

Install All
Install Package
Install Local

Install all dependencies from soul.json:

soul pkg install

Install a specific package:

soul pkg install console
soul pkg install math@1.2.0

Install from local path:

soul pkg install ./local-package
soul pkg install /absolute/path/to/package

`soul pkg list` - List Available Packages

View all packages in the Soul package registry:

soul pkg list

Output includes:

Package names with latest versions
Package descriptions and categories
All available versions
Total package count

`soul pkg search` - Search Packages

Search for packages by name, description, or keywords:

soul pkg search console      # Search for console-related packages
soul pkg search "web server" # Search with multiple words

Search covers:

Package names
Descriptions
Keywords
Categories

`soul pkg validate` - Validate Dependencies

Check package dependencies and version constraints:

soul pkg validate

Validates:

Soul version compatibility
All dependency version constraints
Package compatibility across the project
Displays dependency summary with installed versions

`soul pkg tidy` - Tidy Dependencies

Automatically manage dependencies based on imports:

soul pkg tidy

Features:

Creates soul.json if it doesn’t exist
Scans all .soul files for import statements
Extracts and adds package dependencies
Updates existing soul.json with new dependencies
Ignores relative imports and file paths

`soul pkg clear-cache` - Clear Cache

Clear package cache to force fresh downloads:

soul pkg clear-cache

Clears:

Package download cache
Temporary installation files
Shows freed disk space in human-readable format

Program Structure

Genesis Function

Every Soul program must have exactly one genesis() function as the entry point:

soul genesis() {
    Console.log("Hello, Soul!")
}

soul genesis(args) {  // ❌ Invalid
    Console.log("Hello")
}

soul genesis() { ... }    // ❌ Multiple genesis
soul genesis() { ... }   // functions not allowed

Configuration

Project Configuration (`soul.json`)

Complete example of a soul.json file:

{
  "name": "my-soul-app",
  "version": "1.0.0",
  "description": "My Soul application",
  "license": "MIT",
  "scripts": {
    "start": "soul run app.soul",
    "build": "soul build app.soul",
    "test": "soul run tests/main.soul"
  },
  "dependencies": {
    "console": "latest",
    "math": "^1.0.0",
    "http": "~2.1.0"
  },
  "soulVersion": "^1.0.0"
}

Error Handling

Soul CLI provides detailed error messages and validation:

Genesis Function Errors

Missing genesis function
Multiple genesis functions
Genesis function with parameters
Genesis function validation across multiple files

Dependency Errors

Missing packages
Version constraint conflicts
Soul version compatibility issues
Invalid package specifications

Build Errors

Source file not found
Compilation failures
Permission issues
Disk space issues

Examples

Basic Workflow

# Initialize a new project
mkdir my-soul-app && cd my-soul-app
soul pkg init

# Create main file
echo 'soul genesis() { Console.log("Hello, Soul!") }' > app.soul

# Install dependencies (auto-detected)
soul pkg tidy

# Run the program
soul run app.soul

# Build executable
soul build app.soul

# Run the executable
./app

Package Development

# Create a package
soul pkg init
echo '{"name": "my-package", "version": "1.0.0"}' > soul.json

# Install from local path in another project
cd ../my-app
soul pkg install ../my-package

# Validate all dependencies
soul pkg validate

Development Tips

# Skip validation during development
soul run --skip-validation app.soul

# Build and run quickly
soul build app.soul && ./app

This comprehensive CLI toolkit makes Soul development efficient and manageable, with powerful package management and build tools.

CLI Usage

Modules

Syntaxes

Overview

Global Flags

Core Commands

`soul run` - Execute Soul Programs

`soul build` - Compile Soul Programs

Version Management

`soul version` - Check Version

`soul update` - Update Soul

Package Management

`soul pkg init` - Initialize Package

`soul pkg install` - Install Dependencies

`soul pkg list` - List Available Packages

`soul pkg search` - Search Packages

`soul pkg validate` - Validate Dependencies

`soul pkg tidy` - Tidy Dependencies

`soul pkg clear-cache` - Clear Cache

Program Structure

Genesis Function

Configuration

Project Configuration (`soul.json`)

Error Handling

Examples

Basic Workflow

Package Development

Development Tips

​Overview

​Global Flags

​Core Commands

​soul run - Execute Soul Programs

​soul build - Compile Soul Programs

​Version Management

​soul version - Check Version

​soul update - Update Soul

​Package Management

​soul pkg init - Initialize Package

​soul pkg install - Install Dependencies

​soul pkg list - List Available Packages

​soul pkg search - Search Packages

​soul pkg validate - Validate Dependencies

​soul pkg tidy - Tidy Dependencies

​soul pkg clear-cache - Clear Cache

​Program Structure

​Genesis Function

​Configuration

​Project Configuration (soul.json)

​Error Handling

​Examples

​Basic Workflow

​Package Development

​Development Tips

Overview

Global Flags

Core Commands

`soul run` - Execute Soul Programs

`soul build` - Compile Soul Programs

Version Management

`soul version` - Check Version

`soul update` - Update Soul

Package Management

`soul pkg init` - Initialize Package

`soul pkg install` - Install Dependencies

`soul pkg list` - List Available Packages

`soul pkg search` - Search Packages

`soul pkg validate` - Validate Dependencies

`soul pkg tidy` - Tidy Dependencies

`soul pkg clear-cache` - Clear Cache

Program Structure

Genesis Function

Configuration

Project Configuration (`soul.json`)

Error Handling

Examples

Basic Workflow

Package Development

Development Tips