Skip to main content
The Walrus CLI provides multiple execution modes and debugging capabilities for running your Walrus programs.

​
Basic usage

# Run a script file (bytecode VM mode)
walrus file.walrus

# Start interactive REPL
walrus

# Show help
walrus --help

​
Command-line flags

​
Execution modes

​
-c, --compile
flag
Compile the script to bytecode and execute with the VM (default mode)
walrus --compile program.walrus
This is the default execution mode when a file is provided. The bytecode VM offers better performance than the tree-walking interpreter.
​
-i, --interpreted
flag
Run with the tree-walking interpreter instead of the bytecode VM
walrus --interpreted program.walrus
Useful for development and debugging. Cannot be combined with --disassemble.
​
--disassemble
flag
Print the bytecode disassembly without executing
walrus --disassemble program.walrus
Displays the compiled bytecode instructions for analyzing program structure. Cannot be combined with --interpreted.

​
Debugging and logging

​
-d, --debug
flag
Enable debug-level logging
walrus --debug program.walrus
Shows detailed internal information during execution. Sets log level to Debug.
​
--debugger
flag
Enable interactive debugger mode
walrus --debugger program.walrus
Starts the program in debugger mode with step-through execution, breakpoints, and variable inspection. See Debugging for full debugger documentation.
​
-v, --verbose
flag
Enable verbose output
walrus --verbose program.walrus
Provides additional information during execution.
​
-t, --trace
flag
Enable trace-level logging (most detailed)
walrus --trace program.walrus
Shows extremely detailed trace information for deep debugging. Sets log level to Trace.

​
JIT compilation

These flags require the jit feature to be enabled during compilation.
​
--jit
flag
Enable JIT compilation of hot code paths
walrus --jit program.walrus
Requires Walrus to be built with --features jit. Hot loops are compiled to native machine code using Cranelift after 1000 iterations, providing significant performance improvements for numeric computations.
​
--jit-stats
flag
Show JIT profiling statistics after execution
walrus --jit --jit-stats program.walrus
Displays hot-spot statistics, type profiles, and JIT compilation metrics.Example output:
Hot-spot Statistics:
  Total tracked regions: 3
  Hot loops: 1
  Hot functions: 1
  JIT compiled regions: 1
  Hottest spot: [email protected] (402000x)

Type Profile: 4 locations observed
JIT Stats: 1 functions compiled
​
--no-jit-profile
flag
Disable JIT profiling for baseline benchmarking
walrus --no-jit-profile program.walrus
Turns off profiling overhead to measure baseline VM performance without hot-spot detection.

​
Flag combinations

​
Valid combinations

# Debug mode with JIT stats
walrus --debug --jit --jit-stats program.walrus

# Disassemble with debug logging
walrus --disassemble --debug program.walrus

# Interactive debugger with trace logging
walrus --debugger --trace program.walrus

​
Invalid combinations

Some flags cannot be used together:
Flag 1Flag 2Reason
--interpreted--disassembleInterpreter doesn’t use bytecode
Attempting invalid combinations will result in an error: 
$ walrus --interpreted --disassemble program.walrus
[ERROR] Invalid argument combination: --interpreted and --disassemble

​
File argument

​
file
path
The script file to execute (optional)
walrus script.walrus
If no file is provided, Walrus starts in REPL mode. The file should contain valid Walrus source code with a .walrus extension.

​
Exit codes

The Walrus CLI uses standard exit codes:
CodeMeaning
0Successful execution
1Runtime error or exception
CustomProgram-specific (via sys.exit(code))

​
Examples

​
Basic execution

# Run a program with default settings
walrus fibonacci.walrus

​
Performance optimization

# Enable JIT for maximum performance
walrus --jit benchmark.walrus

# Profile and optimize hot code
walrus --jit --jit-stats compute.walrus

​
Development and debugging

# Inspect bytecode
walrus --disassemble app.walrus

# Debug with detailed logging
walrus --debug --verbose problem.walrus

# Interactive debugging
walrus --debugger app.walrus

​
Interpreter mode

# Use tree-walking interpreter for development
walrus --interpreted development.walrus

Build docs developers (and LLMs) love

Get started for freeTalk to us