# Running BoxLang {% hint style="warning" %} Please check out our [installation page ](https://boxlang.ortusbooks.com/getting-started/installation)to make sure you install the right runtime you want to deploy on. We are assuming you have it installed and `boxlang` and `boxlang-miniserver` are in your machine's path. {% endhint %} {% hint style="info" %} The script for \*nix/Mac is `boxlang` The script for Windows is `boxlang.bat` {% endhint %} ### BoxLang Home By default, once you execute a `boxlang` binary it will look for a `BOXLANG_HOME` environment variable so it can be used as the home for the OS runtime. If you don't provide one, then by default, it will use the currently logged-in user's home folder + `.boxlang` {% tabs %} {% tab title="Mac" %} ```javascript /Users/username/.boxlang ``` {% endtab %} {% tab title="Linux" %} ```bash /home/username/.boxlang ``` {% endtab %} {% tab title="Windows" %} ```python C:\Users\myuser\.boxlang ``` {% endtab %} {% endtabs %} This is important because inside of the home folder, you can have several folders and files by convention that will be used for the runtime execution. {% hint style="danger" %} Please note that each runtime can have a different location for the BoxLang home. So make sure you read each of the runtime's docs to see where each goes. {% endhint %}
Folder/FIleDescription
/classesWhere all the compiled classes will be stored
/configWhere configuration files are stored for the runtime
/config/boxlang.jsonThe runtime configuration file. Here is where you can configure all the settings, caches, datasources, compiler information, and so much more.
/globalWhere global BoxLang classes and component templates can be stored for the entire runtime
/libYou can place any *.jar files here, and they will be loaded into the runtime at startup. This is a great place to put third-party jars that will be available at runtime.
/logsAll log files will be stored here
/modulesHere is where the BoxLang modules are installed and will be available for the entire operating system binary.
version.propertiesThe version information of the installed runtime.
### Start the REPL The first thing you can do is start up the BoxLang REPL, make sure the insaller has added your installation directory to the `PATH` system variable. {% tabs %} {% tab title="Mac/\*nix" %} ```javascript boxlang ``` {% endtab %} {% tab title="Windows" %} ```ruby boxlang.bat ``` {% endtab %} {% tab title="Jar" %} ``` java -jar path/to/boxlang-1.0.0.jar ``` {% endtab %} {% endtabs %}
You can run one-off expressions from the REPL like so: ```shell Enter an expression, then hit enter. Press Ctrl-C to exit. BoxLang> 2+2 4 BoxLang> dateFormat( now(), "full" ) Wednesday, March 13, 2024 BoxLang> "brad".ucase().reverse() DARB BoxLang> a=3 3 BoxLang> b=5 5 BoxLang> a*b 15 BoxLang> ["luis","gavin","jorge"].map( name->name.ucFirst() ) [Luis, Gavin, Jorge] ``` {% hint style="success" %} Press Ctrl-C to exit the REPL or type `exit` or `quit` {% endhint %} Please note that the REPL remembers state, so you can use the variables you declare and build a mini-program with it. ### Executing a File You can also use the `boxlang` binary to execute BoxLang or even CFML code. You can pass a second argument to the binary and it can be a relative (to the current directory you are on) or an absolute path to a file that you wish to execute. {% hint style="info" %} Allowed files are: * `*.bx -` A BoxLang class with a `main( args=[] )` method * \*.bxs - A BoxLang script file * \*.bxm - A Boxlang markup template file If you are using the `bx-compat-cfml` module for CFML Support: * \*.cfs - A CFML script file * \*.cfm - A CFML markup template file {% endhint %} Modify the same command you run above to execute the REPL but add a file path to the end. It can be absolute or relative to the current working directory. {% tabs %} {% tab title="Mac / \*Unix" %} ```bash boxlang task.bx boxlang myscript.bxs boxlang mytemplate.bxm boxlang /full/path/to/test.bxs boxlang /full/path/to/Task.bx ``` {% endtab %} {% tab title="Windows" %} ```powershell boxlang.bat task.bx boxlang.bat myscript.bxs boxlang.bat mytemplate.bxm ``` {% endtab %} {% tab title="Jar" %} ```ruby java -jar boxlang-1.0.0.jar task.bx java -jar boxlang-1.0.0.jar /full/path/to/test.bxs ``` {% endtab %} {% endtabs %} #### Producing Output As you navigate all the built-in functions and capabilities of BoxLang, let's learn how to produce output to the system console. * `printLn()` - Print with a line break * `print()` - Print with no line break * `writeOutput()` - Writes to the output buffer (Each runtime decides what it's buffer is. The CLI is the system output, the Web is the HTML response buffer, etc) ```groovy println( "Time is #now()#" ) ``` I get the output: ```bash ╰─ boxlang test.bxs Time is {ts '2024-05-22 22:09:56'} ``` Hooray! You have executed your first script using BoxLang. Now let's build a class with a `main( args=[] )` convention. This is simliar to Java or Groovy. ```groovy class{ function main( args=[] ){ println( "Task called with " & arguments.toString() ) } } ``` You can now call it with zero or more arguments! ```bash ╰─ boxlang Task.bx Task called with {ARGS=[]} ╰─ boxlang Task.bx boxlang rocks Task called with {ARGS=[boxlang, rocks]} ``` ### One Off Code Execution So, to give a quiet example of the `--bx-code` flag here’s running some one-off code. ```bash boxlang --bx-code "2+2" ``` {% hint style="warning" %} This assumes script, not templating tags. {% endhint %} ### Piping code You can also pipe statements into the BoxLang binary for execution as well. This assumes script, not tags. ```bash echo "2+2" | java -jar boxlang-1.0.0.jar echo "2+2" | boxlang ``` or ```bash # on *nix cat test.cfs | java -jar boxlang-1.0.0.jar cat test.cfs | boxlang # on Windows type test.cfs | java -jar boxlang-1.0.0.jar type test.cfs | boxlang.bat ``` ### Printing the Abstract Syntax Tree (AST) BoxLang can emit the parsed **Abstract Syntax Tree** of any source as JSON, which is useful for tooling, debugging, and editor integrations. There are two ways to access the AST. #### Via the CLI Flag Use the `--bx-printAST` flag with any of the three input modes: ```bash # From a file boxlang --bx-printAST /path/to/MyClass.bx # From inline code boxlang --bx-printAST --bx-code "x = 1 + 2" # From stdin cat MyComponent.bx | boxlang --bx-printAST # Integrate with jq for targeted inspection cat MyComponent.bx | boxlang --bx-printAST | jq '.body[0]' ``` #### Via the `boxAST()` BIF You can also retrieve the AST programmatically at runtime using the `boxAST()` built-in function, which returns the JSON AST of any BoxLang source string: ```js ast = boxAST( "result = 1 + 2" ) writeDump( ast ) ``` {% hint style="info" %} The `boxAST()` BIF is useful for meta-programming, code analysis tooling, or any scenario where you need to inspect the structure of BoxLang code at runtime. {% endhint %} ### Command Line Arguments If you interact with the `boxlang` binary then you will be executing the `BoxRunner` class in BoxLang. You can use several options and positional arguments to our runtime. Let's explore them. #### Options * `--bx-code "code here"`—This is used to pass ad-hoc code to execute. Provide code in the next argument, quoted. * `--bx-config` - Pass a path to a JSON file for BoxLang configuration. See [Runtime Configuration](https://boxlang.ortusbooks.com/getting-started/configuration) for more information. * `--bx-debug` - Enable debug mode (more debug logs!) * `--bx-home` - Pass a path to a custom runtime home directory for storing modules, configuration, and more. See [Runtime Home Directory](https://boxlang.ortusbooks.com/configuration#runtime-home-directory) for more information. * `--bx-printAST` - Prints out BoxLang AST in JSON format for debugging. Supports three input modes: * **File path**: `boxlang --bx-printAST /path/to/MyClass.bx` * **Inline code**: `boxlang --bx-printAST --bx-code "x = 1 + 2"` * **Stdin piping**: `cat MyComponent.bx | boxlang --bx-printAST` * `--bx-transpile` - Prints out transpiled Java source that would be compiled to create the bytecode for the passed template path. (for debugging) * `--version` - Output the current runtime's version information #### Positionals * `script_path | class_path` - The template, class, or script to execute * If it's a class, it must have a `main( args )` method. * `module:{name}` - The executable module to execute. This will execute a Modules' `ModuleConfig.main( args )` method. * `{actionCommand: compile,featureAudit, cftranspile}` - If you send any of those action commands, we will execute those CLI tools ### Using 3rd Party Jars You can load custom third-party JARs at runtime by adding all your `*.jar` to the `BOXLANG_HOME/lib` folder. This will be loaded at runtime and available to use and integrate. ### Environment Variables The `boxlang` binary will also scan for several environment variables as overrides to the execution process. | Env Variable | Purpose | | ----------------------------- | ---------------------------- | | `BOXLANG_CONFIG` = PATH | Override the `boxlang.json` | | `BOXLANG_DEBUG = BOOLEAN` | Enable or disable debug mode | | `BOXLANG_HOME = DIRECTORY` | Override the HOME directory | | `BOXLANG_PRINTAST = BOOLEAN` | Print the AST | | `BOXLANG_TRANSPILE = BOOLEAN` | Tranpile the code | In addition to core runtime OS-level settings, you can also use the environment or Java properties to adjust granular configuration setting. For more [see the Runtime Configuration section](https://boxlang.ortusbooks.com/getting-started/configuration#environmental-properties-configuration). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://boxlang.ortusbooks.com/getting-started/running-boxlang.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.