CLI Reference

The BrainRot Lang CLI is a single binary with four commands. Every command takes a .brt source file as its argument.

Overview

Command	Description	Example
`run`	Execute a `.brt` source file through the full pipeline	`brainrot run hello.brt`
`tokens`	Print the Lexer's token stream — demonstrates Phase 1	`brainrot tokens hello.brt`
`ast`	Print the Parser's Abstract Syntax Tree — demonstrates Phase 2	`brainrot ast hello.brt`
`help`	Show usage information and available commands	`brainrot help`

run — execute a program

The run command is the primary command. It passes the source file through the complete pipeline: Lexer → Parser → AST → Interpreter, printing output to stdout.

terminal

# Run a BrainRot source file
brainrot run hello.brt
brainrot run examples/fibonacci.brt

# Output appears directly in your terminal
# Hello, world!
# 0 1 1 2 3 5 8 13

File format: BrainRot source files use the .brt extension. The file must contain a let_him_cook main() function as the entry point.

tokens — show token stream

The tokens command runs only the Lexer (Phase 1) and prints every token it produces. Use this to see how the DFA-based tokenizer breaks down your source code before parsing.

terminal

# Show the raw token stream from the Lexer
brainrot tokens hello.brt

# Example output:
# Token{Type:FUNCTION_DECL, Literal:"let_him_cook"}
# Token{Type:IDENT, Literal:"main"}
# Token{Type:LPAREN, Literal:"("}
# Token{Type:RPAREN, Literal:")"}
# Token{Type:LBRACE, Literal:"{"}
# Token{Type:PRINT, Literal:"say_my_name"}
# Token{Type:LPAREN, Literal:"("}
# Token{Type:STRING, Literal:"Hello, world!"}
# Token{Type:RPAREN, Literal:")"}
# Token{Type:RBRACE, Literal:"}"}
# Token{Type:EOF, Literal:""}

ast — show syntax tree

The ast command runs the Lexer and Parser (Phases 1 & 2) and prints the Abstract Syntax Tree. Use this to verify how the parser interpreted your program structure, operator precedence, and expression nesting.

terminal

# Show the full Abstract Syntax Tree from the Parser
brainrot ast hello.brt

# Example output (condensed):
# Program
# └── FuncDecl: main
#     └── PrintStatement
#         └── StringLiteral: "Hello, world!"

help — usage information

The help command (or --help / -h flag) prints usage information and exits.

terminal

# Show usage information
brainrot help
brainrot --help
brainrot -h

# Output:
# BrainRot Lang v1.0.0
# Usage: brainrot <command> <file>
#
# Commands:
#   run      Execute a .brt source file
#   tokens   Display the lexer token stream
#   ast      Display the parsed AST
#   help     Show this help message

Build from Source

BrainRot Lang is written in Go. You can build it from source with a single command. Go's cross-compilation support means you can build for any target OS from any host OS.

terminal

# Build for current OS
go build -o brainrot main.go

# Cross-compile for Windows (from Mac/Linux)
GOOS=windows GOARCH=amd64 go build -o brainrot.exe main.go

# Cross-compile for macOS (from Windows)
GOOS=darwin GOARCH=amd64 go build -o brainrot main.go

# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o brainrot main.go

# Run without building
go run main.go run examples/fibonacci.brt

← Examples Flags →