CLI Reference

The sigil command-line tool provides all development and runtime functionality.

Running Programs

Evaluating Files

sigil eval -f <file.sgl>

Runs the specified Sigil source file.

Example:

sigil eval -f hello.sgl

Evaluating Expressions

sigil eval '<expression>'

Evaluates a Sigil expression and prints the result.

Examples:

sigil eval '(+ 1 2 3)'
# Output: 6

sigil eval '(println "Hello!")'
# Output: Hello!

Adding Library Paths

Use -L to add directories to the library search path:

sigil eval -L lib -f main.sgl

Interactive REPL

sigil repl

Starts an interactive Read-Eval-Print Loop. Type expressions to evaluate them. Press Ctrl+D or type ,q to exit.

Building Projects

`sigil build`

Build a package and its dependencies:

sigil build                        # Build all workspace packages
sigil build sigil-json             # Build specific package with deps
sigil build sigil-cli --config release  # Build with specific config

Configurations:

dev — Development build (default)
debug — Debug build with symbols
release — Optimized release build with modules bundled into a self-contained executable

Running Your Application

`sigil run`

Build and run your application:

sigil run                          # Build dev config and run entry point
sigil run --config release         # Build release config and run
sigil run -t <task-name>           # Run a specific task instead

The sigil run command automatically builds any out-of-date modules before running the application's entry point (defined by entry: in package.sgl).

Use -t or --task to run a specific task defined in package.sgl instead of the entry point.

Testing

`sigil test`

Run project tests:

sigil test
sigil test <pattern>  # Run matching tests

Other Commands

`sigil repl`

Start an interactive REPL:

sigil repl

`sigil format`

Format Sigil source files:

sigil format <file.sgl>
sigil format --check <file.sgl>  # Check without modifying

`sigil docs`

Documentation tools:

sigil docs build <source> <output>
sigil docs serve <output>

`sigil cli`

CLI management commands:

sigil cli install     # Install sigil to ~/.sigil
sigil cli upgrade     # Download latest version
sigil cli use <ver>   # Switch to a specific version
sigil cli versions    # List installed versions
sigil cli prune       # Remove old versions
sigil cli env         # Print shell configuration

`sigil changes`

Release management:

sigil changes new              # Create a new changeset
sigil changes status           # Show pending changes
sigil changes version          # Bump version based on changes
sigil changes changelog        # Generate changelog

Global Options

Option	Description
`-v`, `--verbose`	Verbose output
`-q`, `--quiet`	Minimal output
`--version`	Show version
`--help`	Show help

Environment Variables

Variable	Description	Default
`SIGIL_PATH`	Library search path (colon-separated)	Current directory
`SIGIL_HOME`	Sigil installation and global dependency-state directory	`~/.sigil`
`NO_COLOR`	Disable colored output	Not set
`SIGIL_DEPS_TRACE_DROPPED`	Set to `1` to trace dependency constraints the resolver discarded	Not set

Tracing discarded dependency constraints

The resolver deduplicates by package name: the first declaration of a package to be resolved wins, and any later version range for that same name is discarded. This is normal and usually correct, because a library declaring sigil: "^0.17" is stating what it was built against rather than pinning the host's runtime.

It also means a version range you wrote in package.sgl can have no effect on the resolve, with nothing in the output saying so. SIGIL_DEPS_TRACE_DROPPED=1 makes those discards visible:

SIGIL_DEPS_TRACE_DROPPED=1 sigil deps install

Each discarded constraint prints one line on stderr:

DROPPED <site> <package> want=<range> have=<version> <verdict>

Field	Meaning
`site`	`git-dep`, `workspace-member`, or `transitive` — which resolution path the discarded constraint arrived on
`want`	the range that was discarded, or `-` when the arrival path carries no range
`have`	the version already resolved for that package
`verdict`	`SATISFIED` (the resolved version meets the discarded range), `UNSATISFIED` (it does not), `NO-RANGE`, `UNPARSEABLE`, or `UNKNOWN-INSTALLED-VERSION`

UNSATISFIED on an ordinary package is the interesting case: something in your dependency graph asked for a version range that the resolve does not meet, and the build is proceeding anyway. UNSATISFIED on sigil-lib or sigil-stdlib is expected and not a problem — the runtime family follows the host project's sigil: field, so a dependency's own range for it is advisory.

The trace never changes what gets resolved. It only reports.

Exit Codes

Code	Meaning
0	Success
1	General error
2	Command-line usage error
3	Compilation error
4	Runtime error

Examples

Development Workflow

# Create and run a new project
sigil init my-app
cd my-app
sigil run                          # Build and run the app

# Run a standalone script
sigil eval -f myprogram.sgl

# Run with library path
sigil eval -L lib -f main.sgl

# Start REPL for experimentation
sigil repl

Building for Distribution

# Build a package
sigil build sigil-cli --config release

# Install the CLI
./build/release/bin/sigil cli install

Running Tests

# Run all tests
sigil test

# Run specific tests
sigil test "test-parser"