CLI Reference

Complete reference for the braidc compiler CLI. The compiler is the primary tool for developing, building, and running Braid programs.

Usage

braidc <command> [options] <file>

Pipeline Commands

braidc parse

Lex and parse Braid source, validating syntax. Returns a span descriptor on success or error messages on failure.

braidc parse hello.br
# Output: ModuleSpan(1:1-1:1)

braidc ast

Parse and output the full AST tree as serialized text. Useful for debugging parser output.

braidc ast hello.br
# Output:
# Module {
#   Function main() {
#     Block {
#       Call print [args: [Literal "Hello, Braid!"]]
#     }
#   }
# }

braidc ir

Lower AST to Braid IR (SSA form) and display. Shows functions with their IR instructions including opcodes and operands.

braidc ir hello.br
# Output:
# module hello {
#   func main {
#     %val0 = const i64 42
#     %val1 = const i64 1
#     %val2 = add_i64 %val0, %val1
#     %val3 = call print(%val2)
#     %val4 = const i64 0
#     return %val4
#   }
# }

braidc mlir

Convert Braid IR to MLIR dialect. Currently a stub that outputs a mock MLIR module.

braidc mlir hello.br
# Output:
# module {
#   func.func @main() -> i64 {
#     %0 = braidcore.constant 1 : i64
#     %1 = braidcore.constant 2 : i64
#     %2 = braidcore.add_i64 %0, %1 : i64
#     return %2 : i64
#   }
# }

braidc llvm

Emit LLVM IR from the Braid program. Currently a stub that outputs mock LLVM IR.

braidc llvm hello.br
# Output:
# define i64 @main() {
#   %1 = add i64 1, 2
#   ret i64 %1
# }

braidc ccodegen

Generate C source code from Braid source. The output is compilable with GCC/Clang.

braidc ccodegen hello.br
# Output:
# #include <stdio.h>
# #include <stdlib.h>
# #include <stdint.h>
# #include <stdbool.h>
# int main() {
#     printf("Hello, Braid!\n");
#     return 0;
# }

braidc build

Build a .bx bytecode artifact from Braid source. Requires -o <output> flag.

braidc build hello.br -o hello.bx
# Creates hello.bx with BRDC header and LLVM IR payload

Execution Commands

braidc run

Run a .br source file or .bx bytecode file. For .br, the pipeline is: parse → ccodegen → compile (gcc) → execute. For .bx, the bytecode is loaded and executed by the BraidVM.

braidc run hello.br
# Compiles to C, compiles with gcc, runs
# Output: Hello, Braid!
# Execution complete. Exit code: 0

braidc run hello.bx
# Loads bytecode into VM, executes
# Output: Hello, Braid!
# Execution complete. Result: 0

Framework Commands

braidc frontend

Manage Braid Frontend (Bond/Blend/Link/Merge) projects.

braidc frontend new myapp     # Create new frontend project
braidc frontend routes       # Parse routes from application
braidc frontend state        # Initialize state management
braidc frontend render       # Render UI components
braidc frontend test         # Run frontend tests
braidc frontend build -o f   # Build frontend artifact
braidc frontend check        # Validate frontend config
braidc frontend dev          # Generate dev server manifest

braidc junction

Manage Junction fullstack applications.

braidc junction new myapp    # Create new Junction app
braidc junction dev          # Start dev server on port 8080
braidc junction test         # Run tests (3 passing)
braidc junction build -o f   # Build Junction app bytecode
braidc junction run          # Run Junction app
braidc junction routes       # List Junction routes
braidc junction check        # Validate Junction project

Utility Commands

braidc nl

Process a natural language command. Returns a semantic graph representation of the intent.

braidc nl "build and run my project"
# Output: SemanticGraph { Plan: Audit repo }

braidc help

Display the full help message listing all commands and examples.

braidc help
# or
braidc --help

Exit Codes