CLI Reference

Master the Nebula command-line interface.

Quick Reference

Command	Description
nebula file.na	Run with interpreter
nebula --vm file.na	Run with VM (faster)
nebula	Start REPL
nebula --help	Show help

Running Scripts

Interpreter Mode

The tree-walking interpreter is great for development:

nebula script.na

Pros:

• Faster startup time
• Better error messages
• Good for small scripts

VM Mode (Recommended)

The bytecode VM provides better performance:

nebula --vm script.na

Pros:

• Up to 4x faster execution
• Optimized for loops and recursion
• Production ready

When to Use Each

Use Case	Recommended
Quick scripts	Interpreter
Benchmarks	VM
Production	VM
Debugging	Interpreter
Large programs	VM

Interactive REPL

Start an interactive session:

nebula

Or with VM backend:

nebula --vm

REPL Features

nebula> 2 + 2
4

nebula> perm x = 10
nebula> x * 5
50

nebula> fn double(n) = n * 2
nebula> double(25)
50

nebula> [1, 2, 3].map(double)
[2, 4, 6]

REPL Commands

Input	Action
Expression	Evaluate and print result
Statement	Execute silently
Empty line	Continue
Ctrl+C	Cancel current input
Ctrl+D	Exit REPL

File Extension

Nebula source files use .na:

project/
├── main.na
├── utils.na
├── lib/
│   └── math.na
└── tests/
    └── test_math.na

Exit Codes

Code	Meaning
0	Success
1	Runtime error
2	Parse error
3	File not found

Using in Scripts

#!/bin/bash
nebula --vm script.na
if [ $? -eq 0 ]; then
    echo "Success!"
else
    echo "Failed!"
fi

Environment Variables

Variable	Description	Default
NEBULA_PATH	Module search path	.
NEBULA_DEBUG	Enable debug output	0

NEBULA_DEBUG=1 nebula --vm script.na

Examples

Run a Simple Script

echo 'log("Hello!")' > hello.na
nebula hello.na
# Output: Hello!

Benchmark Comparison

time nebula script.na      # Interpreter
time nebula --vm script.na # VM (typically faster)

Piping Input

echo "Alice" | nebula input_program.na

Running from Different Directory

nebula /path/to/project/main.na