Command Line

Complete reference for the quartz command-line interface.

Synopsis

quartz [options] [script.qz] [arguments...]
quartz [options] script.qzb [arguments...]

Description

The quartz command runs Quartz scripts in interpreter or bytecode mode. It can also compile scripts to bytecode for later execution.

Basic Usage

Run a Script

# Run with interpreter (default)
quartz script.qz

# Run with bytecode VM
quartz -c script.qz

# Run precompiled bytecode
quartz script.qzb

Pass Arguments

# Arguments after script name are passed to the program
quartz script.qz arg1 arg2 arg3

Access arguments in your script:

import system.runtime as rt

let args = rt.args()
for (let i = 0; i < len(args); i = i + 1) {
io.println("Arg " + i + ": " + args[i])
}

Options

Execution Mode

Option	Description
`-c`, `--compile`	Compile to bytecode and run (faster execution)
`-b`, `--bytecode`	Compile to .qzb file (ahead-of-time compilation)
`-i`, `--interpret`	Force interpreter mode (default for .qz files)

Output Options

Option	Description
`-o FILE`, `--output FILE`	Specify output file for bytecode compilation
`--dump-ast`	Print AST and exit (debugging)
`--dump-bytecode`	Print bytecode disassembly and exit
`--dump-tokens`	Print lexer tokens and exit

Extension Options

Option	Description
`-e DIR`, `--ext-dir DIR`	Add extension search directory
`--no-stdlib`	Don't load standard library extensions

Debug Options

Option	Description
`-v`, `--verbose`	Enable verbose output
`--trace`	Trace execution (very verbose)
`--time`	Print execution time

Information Options

Option	Description
`-h`, `--help`	Show help message
`-V`, `--version`	Show version information

Examples

Run a Script

# Basic execution
quartz hello.qz

# With arguments
quartz calculator.qz add 5 3

Bytecode Compilation

# Compile and run immediately
quartz -c script.qz

# Compile to file
quartz -b script.qz
# Creates: script.qzb

# Compile with custom output name
quartz -b script.qz -o build/app.qzb

# Run compiled bytecode
quartz build/app.qzb

Debugging

# See lexer tokens
quartz --dump-tokens script.qz

# See AST
quartz --dump-ast script.qz

# See bytecode
quartz -c --dump-bytecode script.qz

# Verbose execution
quartz -v script.qz

# Trace every instruction
quartz -c --trace script.qz

Performance

# Time execution
quartz --time script.qz

# Compare modes
quartz --time script.qz
quartz -c --time script.qz

Custom Extensions

# Add custom extension directory
quartz -e ./my_extensions script.qz

# Multiple extension directories
quartz -e ./ext1 -e ./ext2 script.qz

# Run without standard library (bare bones)
quartz --no-stdlib minimal.qz

Environment Variables

Variable	Description
`QUARTZ_PATH`	Colon-separated list of extension search paths
`QUARTZ_HOME`	Quartz installation directory
`QUARTZ_DEBUG`	Enable debug mode (1 = on)

Example:

export QUARTZ_PATH="$HOME/.quartz/extensions:/opt/quartz/ext"
quartz script.qz

Exit Codes

Code	Description
`0`	Success
`1`	Runtime error
`2`	Syntax error
`3`	File not found
`4`	Extension load error
`65`	Invalid arguments

File Types

Extension	Type	Description
`.qz`	Source	Quartz source code
`.qzb`	Bytecode	Compiled bytecode
`.so`	Extension	Native extension (Linux/macOS)
`.dll`	Extension	Native extension (Windows)

Typical Workflows

Development

# Quick iteration cycle
quartz script.qz

# Debug issues
quartz -v script.qz

Production

# Pre-compile for deployment
quartz -b app.qz -o dist/app.qzb

# Run in production
quartz dist/app.qzb

Benchmarking

# Compare execution modes
echo "Interpreter:"
quartz --time bench.qz

echo "Bytecode:"
quartz -c --time bench.qz

💡 Tip For production deployments, always use -b to pre-compile your scripts. This eliminates parsing overhead and protects your source code.