Boxlang Runtime CLI Scripting

BoxLang CLI Scripting

Overview

The boxlang binary can run scripts, classes, templates, and inline code directly from the command line. It supports multiple file types, shebang lines, structured argument parsing, and a built-in REPL.

Supported File Types

Running Files

# Class with main() method
boxlang MyApp.bx

# Script file
boxlang process.bxs --config=prod.json --debug

# Template file
boxlang render.bxm

# Inline code
boxlang --bx-code "println( 'Hello!' )"

# From stdin
echo "println( 'piped!' )" | boxlang

# REPL (no arguments)
boxlang

Class Entry Point (main)

Use .bx files with a main() method for structured CLI applications:

class MyApp {
    static function main( args = [] ) {
        var parsed = CLIGetArgs()
        println( "Options: " & parsed.options.toString() )
        println( "Positionals: " & parsed.positionals.toString() )
    }
}

Argument Parsing

BoxLang parses CLI arguments automatically. Access them via CLIGetArgs() or server.cli.parsed:

// In a .bxs script
var args = CLIGetArgs()
// args = { options: { debug: true, config: "prod.json" }, positionals: [ "file.txt" ] }

var debug = args.options.debug ?: false
var config = args.options.config ?: "default.json"

Argument Formats

Example

boxlang myscript.bxs --debug --!verbose --config=prod.json -o='/tmp/out' report.txt

Results in:

{
    "options": {
        "debug": true,
        "verbose": false,
        "config": "prod.json",
        "o": "/tmp/out"
    },
    "positionals": [ "report.txt" ]
}

Shebang Scripts

Make scripts directly executable with a shebang line:

#!/usr/bin/env boxlang
println( "I run directly!" )
var args = CLIGetArgs()
println( args.toString() )

chmod +x myscript.bxs
./myscript.bxs --name=World

CLI Built-In Functions

// Interactive prompt
var name = CLIRead( "Enter your name: " )
println( "Hello, " & name )

// Exit with error code
if ( !fileExists( configFile ) ) {
    println( "Error: config not found" )
    CLIExit( 1 )
}

CLI Flags

# Run with custom config and debug
boxlang --bx-debug --bx-config ./config/boxlang.json myapp.bxs

# Print the AST
boxlang --bx-printAST myscript.bxs

# Inline execution
boxlang --bx-code "println( now() )"

Action Commands

Run via boxlang <action> [options] — these compile, convert, or audit code.

compile — Compile to bytecode

boxlang compile --source ./src --target ./compiled

Options: --source <path>, --target <path>, --recurse true/false

cftranspile — Transpile CFML to BoxLang

boxlang cftranspile --source ./legacy-cfml --target ./bx-src

Options: --source <path>, --target <path>, --recurse true/false

featureaudit — Audit CFML compatibility

boxlang featureaudit --source ./legacy-cfml

Reports unsupported or incompatible CFML patterns.

schedule — Run a scheduler file

boxlang schedule ./schedulers/MainScheduler.bx

Runs continuously until Ctrl+C. File must be a .bx class with scheduler definitions.

Runtime Detection

Detect the execution context in BoxLang code:

// CLI mode vs web server vs JAR mode
if ( server.boxlang.cliMode ) {
    println( "Running in CLI mode" )
} else if ( server.boxlang.jarMode ) {
    println( "Running as embedded JAR" )
}

// Access parsed CLI arguments
var parsed = server.cli.parsed
// { options: {}, positionals: [] }

// Runtime info
println( server.boxlang.runtimeHome )
println( server.coldfusion.productVersion )  // BoxLang version

Available Scopes in CLI Mode

REPL Mode

Start with no arguments for an interactive session:

boxlang
# BoxLang> println( "Hello!" )
# Hello!
# BoxLang> 1 + 1
# 2
# BoxLang> :history    (show history)
# BoxLang> :clear      (clear screen)
# BoxLang> Ctrl+C      (exit)

• Supports multi-line input (continues on unbalanced braces)
• !! repeats last command; !n repeats command n
• :dark / :light switch color themes

Example Script Patterns

Script with validation

// validate-args.bxs
var args = CLIGetArgs()

if ( args.positionals.isEmpty() ) {
    println( "Usage: boxlang validate-args.bxs <filename> [--verbose]" )
    CLIExit( 1 )
}

var file = args.positionals[1]
var verbose = args.options.verbose ?: false

if ( !fileExists( file ) ) {
    println( "Error: File not found: " & file )
    CLIExit( 2 )
}

println( "Processing: " & file )

Class with structured main

// DataProcessor.bx
class DataProcessor {
    static function main( args = [] ) {
        var opts = CLIGetArgs().options
        var inputFile  = opts.input  ?: throw( "--input is required" )
        var outputFile = opts.output ?: "output.json"
        var debug      = opts.debug  ?: false

        if ( debug ) println( "Input:  " & inputFile )
        if ( debug ) println( "Output: " & outputFile )

        // process...
    }
}

Checklist

• Use CLIGetArgs() for all argument access (not raw args array)
• Validate required arguments and call CLIExit( 1 ) on error
• Use --bx-config / BOXLANG_CONFIG to separate config from code
• Use server.boxlang.cliMode for runtime-aware conditional logic
• Prefer .bx classes with main() for reusable, testable entry points
• Use #!/usr/bin/env boxlang shebang for directly executable scripts
• Use CLIRead() for interactive prompts; CLIClear() for UI scripts