CLI Reference

The scar command-line interface — run programs, build binaries, and check versions.

Usage

ScarScript compiler v1.0.0

Usage:
  scar run <file.scar>              Compile and run a program
  scar build <file.scar> [-o out]   Compile to a native binary
  scar version                      Print version
  scar help                         Show this help

Commands

scar run

Compiles the file and executes it immediately. Uses a temporary directory for the generated Go source.

$ scar run hello.scar
Hello, Zawiyar!

Argument	Required	Description
`<file.scar>`	Yes	Path to the source file

Go required: scar run invokes go run under the hood, so Go 1.22+ must be on your PATH. For a Go-free workflow, use scar build on a machine with Go, then ship the binary.

scar build

Compiles the file into a standalone native binary. The output has zero runtime dependencies.

# Default output name (derived from source file)
$ scar build hello.scar
built hello

# Custom output name
$ scar build hello.scar -o myapp
built myapp

# Windows
> scar build hello.scar -o hello.exe
built hello.exe

Argument	Required	Description
`<file.scar>`	Yes	Path to the source file
`-o out`	No	Output binary path (defaults to source name)

Deployment: The built binary is self-contained. Copy it to any matching OS/arch machine and run it — no ScarScript, no Go, no dependencies.

scar version

Prints the compiler version. Aliases: --version, -v.

$ scar version
scar version 1.0.0

scar help

Prints usage information. Aliases: --help, -h.

$ scar help

Exit Codes

Code	Meaning
`0`	Success
`1`	Compilation error (lex/parse/check/codegen)
`2`	Usage error (wrong arguments, no args)

Error Format

All compiler errors follow the same machine-parseable format:

file.scar:LINE:COL: error: MESSAGE

Examples:

// Type mismatch
demo.scar:10:5: error: expected str, got int

// Argument type
demo.scar:10:5: error: argument 1 expects int, got dec

// Missing return
demo.scar:8:1: error: missing return

// Reserved name
demo.scar:5:1: error: "print" is a builtin — cannot be redeclared

// Inference failure
demo.scar:9:9: error: cannot infer type

Editor integration: The file:line:col: error: format is understood by VS Code, Vim/Neovim, and most Go-aware editors out of the box.

Compilation Pipeline

Every scar run / scar build executes these stages in order:

Source (.scar)
      │
      ▼
  ┌────────┐
  │ Lexer  │  Tokens with positions
  └───┬────┘
      ▼
  ┌────────┐
  │ Parser │  AST (panic on syntax error)
  └───┬────┘
      ▼
  ┌─────────┐
  │ Checker │  Static types (first error aborts)
  └───┬─────┘
      ▼
  ┌─────────┐
  │ Codegen │  Self-contained .gen.go (gofmt'd)
  └───┬─────┘
      ▼
  go run / go build  →  native binary