Download Bolt from the official distribution and verify signed artifacts before running binaries. After installation confirm the runtime is accessible from your shell.
Verify installation
bolt --version
Canonical output sample to expect (example):
Bolt Runtime Engine v1.X.X (V: official=X/X)
[build metadata and release date fields here]
This version was released on 202X-0X-0X proudly built by the Swifteex Studio build system.
Please verify signed artifacts before running.
Release metadata and authorship are published with the builds. For reference, this documentation was produced with contributions by 0 and distributed by 1 (a 2 company).
If your output follows the layout above and reports at least v1.61+ you will be able to use typed helpers. For v1.70 specific features (module files, runtime bytecode flow, and pre-baked libraries) the runtime must report v1.70+.
Bolt v1.70 introduces a simple edit-compile-run workflow producing a portable virtual-machine bytecode (.bvmb) file. This section describes the recommended developer workflow.
Step-by-step: write → compile → run
Create your source file
Save your script with the new .bolt extension (previously .blt).
Open a command prompt / terminal in the folder where your file is located
Use your system terminal (PowerShell, Command Prompt, bash, etc.).
Compile (generate bytecode)
Run the compiler switch specifying your .bolt file:
Bolt -c filename.bolt
If compilation succeeds a filename.bvmb file (Bolt Virtual Machine Bytecode) will be produced in the same folder. If there are errors, the compiler will print diagnostic info and exit with a non-zero exit code.
Run the bytecode
Execute the produced bytecode with the runtime:
bolt filename.bvmb
The runtime executes the bytecode; use --debug or --json-errors for diagnostics in automation or CI.
Notes:
Compilation is optional for quick interactive experiments (some runtimes still support direct --run), but the -c → .bvmb approach ensures consistent, distributable artifacts for shipping and automation.
Bytecode files are portable across compatible minor releases; include version metadata during compilation if portability across patch-level runtimes is required.
Command Line Interface
Flags and runtime modes in Bolt. Combine them to fit your workflow.
--run [files...] - execute .bolt or .bvmb files
--exec-string "<source>" - run inline source
--cmd - single-line interactive mode
--safe - sandbox mode (blocks interactive and unsafe built-ins)
--debug - verbose logging and tracebacks
--inspect-ast - print AST before execution for diagnostics
--json-errors - machine-readable error output for CI
bolt --safe --debug --run myscript.bolt
# or run compiled bytecode:
bolt myscript.bvmb
New Syntax - v1.61+ Quick Reference
This section focuses on syntax and features available from Bolt v1.61+. v1.70 keeps compatibility while adding modules and runtime bytecode workflow. For in-depth coverage see the Syntax - Deep Reference section which expands every entry below into a full how-to, troubleshooting, purpose, and requirements article.
Printing - sys.out
What it is and what it does (short):sys.out writes text or evaluated tokens to standard output. Use forward slashes to expand variables inside output: /var/.
sys.out 'hello, world!'
name = 'Ariyan'
sys.out /name/
num1 = 10
num2 = 15
sys.out /num1/ + /num2/
sys.out 'the calculation is /num1 + num2/'
If you see literal tokens such as "/name/" in output, confirm the variable is defined and that you used forward slashes without spaces. For complete guidance and troubleshooting see the deep reference below.
Variables
Assignment uses equals. Starting with v1.61+ integers and numeric types are available and usable in arithmetic.
myvariable = 'Alice'
age = 11
sys.out /myvariable/
sys.out /age/
For values coming from user input, prefer the typed input helpers below to ensure numeric types.
Lists
Create lists with let.list['a' ; 'b']. Index with 0-based notation. Example shown uses the strict form requested below.
Indexes start at 0. Accessing an index outside the valid range is an error; ensure your index is valid before accessing list elements.
Functions and invocation
Functions are declared with fn name(); ... end. The helper let.call name() is available and standard on v1.61+. Many stable runtimes also allow direct invocation such as name().
fn greet(name);
sys.out 'hello /name/!'
end
let.call greet(ariyan)
Make sure functions are defined before invoking them, or call at runtime after the definition section.
Typed input helpers (v1.61+)
In v1.61+ Bolt provides typed input helpers to capture typed values directly: let.userinput.int 'prompt' for integers and let.userinput.str 'prompt' for strings. These reduce bookkeeping and parsing in common interactive scripts.
num = let.userinput.int 'enter a number: '
name = let.userinput.str 'enter your name: '
If you need to support older runtime versions, detect version via bolt --version and fall back to parsing raw input where necessary.
Control flow - if, eif, else
v1.61+ includes the familiar conditional ladder: if, eif for else-if, and else for fallback. Use end.if to close the block.
Bolt v1.70 introduces a simple module system that allows packaging reusable code into .boltmodule files and importing them into scripts. Modules are intended for distribution and reuse across projects.
Creating a module file
Save the module as mymodule.boltmodule. The top-level module wrapper must follow this exact form:
public.module[modulename$1] {{
# module public API and implementation
fn module_init();
# initialization code
end
# helper functions, variables, etc.
some_helper = 'value'
}}
Important: the name inside public.module[...] must match the module filename identifier and the import reference. The $1 suffix denotes the exported major API slot and aids versioning; treat it as part of the module identifier.
Importing modules
Use the import helper $get.module to load a module at runtime. Examples:
# simple import
$get.module
# import with alias
$get.modulename $; aliasname # No need to add '$1' because it is only to give bolt module manager permission to import. It will cause a error if included.
# call exported initialization
let.call mymod.module_init()
The left-hand $get.module form loads the module into the current scope; when using aliasing the module's public symbols are referenced via the alias.
Packaging & distribution notes
Ship .boltmodule with a small manifest containing name, version, and compat (minimum bolt runtime version).
Prefer explicit public APIs (document which functions/variables are public) and avoid global mutable state across modules.
Pre-baked Libraries (v1.70)
v1.70 ships with a small set of convenience libraries for common tasks. They are optional runtime modules; include them by importing or referencing the runtime-provided namespace per your packaging.
Boltclock
Utilities for deterministic pauses and simple scheduling.
# pause for 2 seconds
Boltclock.pause(2)
# combine with function calls
fn afterwait();
sys.out 'resuming after wait'
end
Boltclock.pause(1)
let.call afterwait()
Boltclock.pause(sec) accepts numeric seconds. Implementation may block the current execution context; avoid in high-concurrency scenarios or use cooperative patterns.
Boltloop
Simple repeated execution helper. Use for fixed-count repetition where no loop keywords exist.
# call sys.out 5 times
boltloop.loop(sys.out 'tick') ! 5
# or call a function repeatedly
fn tick();
sys.out 'tick from function'
end
boltloop.loop(tick) ! 3
Syntax: boltloop.loop(instruction) ! times. instruction may be a sys.out, a function identifier, or any single-call instruction supported by the runtime. The runtime treats this as a convenience expansion into repeated calls; heavy repetition should be implemented with careful function design to preserve stack and memory safety.
Random
Pick random items from a provided list or data arguments.
# pick and print one of the arguments
Random.main('data1', 'data2', 'data3')
# store result (example pattern - adapt per runtime API)
choice = Random.main('red','blue','green')
sys.out /choice/
Behavior: Random.main(...) returns a single random item from the arguments and prints it when used inline as shown. Confirm exact return semantics on your runtime (some variants print and return; others only return).
void.0 - runtime stop
To immediately halt Bolt execution from your script use the sentinel void.0. This provides a clean, immediate stop without raising a runtime exception (useful for controlled termination in tools and interactive sessions).
sys.out 'starting'
void.0
# code below will not execute
Syntax - Deep Reference (complete how-to, purpose, fixes, requirements)
This section expands each syntax element into a focused article: purpose, exact syntax, usage examples, common failure modes and how to fix them, and runtime/compatibility requirements. These pages are intentionally prescriptive and strict: examples follow Bolt v1.61+ rules and avoid language constructs not present in Bolt (no for/while loops, no Python syntax). If your target runtime is older than v1.61, consult the compatibility notes inside each article.
Printing - sys.out (deep)
Purpose
Provide deterministic output to stdout. It is the primary and only documented mechanism for emitting textual results, diagnostic messages, and computed numeric values to the user or to a capturing process.
Exact syntax
sys.out 'literal string' - prints the literal string verbatim. sys.out /identifier/ - prints the value of a variable named identifier. Forward-slash interpolation is token-based: wrap a single identifier or an expression token between slashes to evaluate and embed it.
Variable interpolation rules
Interpolation tokens are delimited with forward slashes: /.../.
Inside an interpolation token place a single variable or a numeric expression built from numeric variables and literal numbers using Bolt operators. Example: /num1 + num2/.
If the token is strictly textual (string variable), it expands to the string value. If numeric, it expands to the computed numeric result.
Do not include whitespace between the slashes and the token name if you expect expansion; tokens with leading/trailing spaces are treated literally.
Escaping and literal slashes
To emit raw forward-slashes or sequences that look like tokens, break the string into separate sys.out calls or avoid token syntax. Bolt does not provide an escape sequence inside a single-quoted sys.out literal for forward-slash interpolation. Example safe pattern:
sys.out 'path: /usr/bin'
# To show '/name/' literally - avoid token parsing:
sys.out 'name literal: /name/'
Examples
name = 'Ariyan'
sys.out /name/
a = 5
b = 7
sys.out /a/ + /b/
sys.out 'the sum is /a + b/'
Common errors & fixes
Tokens printed verbatim: If you see /var/ in output, confirm the variable is defined and that the token contains only the identifier or a valid expression. Fix: define the variable before printing or correct token content.
Requirements & runtime notes
The interpolation behavior described assumes Bolt v1.61+ (typed inputs and numeric expression evaluation in tokens). Older runtimes may not evaluate expressions inside tokens; prefer explicit arithmetic and concatenation in that case.
Variables - Declaration & Types
Purpose
Hold immutable or mutable values (strings, integers, numeric types, lists). Bolt uses a simple assignment model: the "=" operator binds the right-hand expression to the identifier on the left.
Exact syntax and semantics
identifier = expression
Identifiers must start with a letter and may contain letters, digits, and underscores.
Strings are single-quoted: 'text'.
Numbers are unquoted numeric literals: 42.
Once assigned, variables are available for interpolation and arithmetic per their type.
Bolt v1.61+ supports numeric types; avoid implicit conversions. When reading from untyped sources (raw prompts without typed helpers) convert with tonumber() if available, otherwise validate and re-prompt.
String used in numeric expression: Convert strings to numbers or use typed input helpers. Fix: use let.userinput.int or tonumber().
Requirements
Typed numeric operations require v1.61+ to ensure numeric types from let.userinput.int. If you must support older runtimes, include defensive parsing and error messages.
Lists - Creation, Indexing, Length
Purpose
Lists are simple ordered collections providing indexed access using 0-based positions. They are ideal for small tables, argument lists, and configuration arrays.
Exact syntax
let.list['item1' ; 'item2' ; 'itemN'] constructs a list. Index with square brackets: listVar[index]. Example below follows the strict form requested.
Accessing an index outside the valid range is an error. Ensure the index value you use is valid before accessing a list element.
List contents may be mixed types; be careful when using items in numeric expressions.
Common errors & fixes
Out-of-range access: Ensure the index is within the valid range before accessing a list element.
Unexpected type inside list: Validate contents before arithmetic (for example, ensure an item is numeric when used in a calculation).
Requirements & notes
List operations are available in v1.61+ as shown. There are no built-in loop constructs to iterate lists; iterate by index with repeated conditionals or by using function-driven repetition patterns. See "Control Flow" for alternative patterns.
Functions - Declaration, Invocation, Conventions
Purpose
Functions encapsulate logic and allow reuse. Bolt uses a compact declaration and a predictable call model. They are the recommended mechanism for structuring logic, including repetition where no loop constructs exist.
Exact syntax
Declare: fn name(); ... end
Invoke: let.call name() or, on many runtimes, direct invocation name().
Examples
fn greet();
sys.out 'hello'
end
let.call greet()
Arguments and returns (pattern)
Bolt v1.61+ does not support formal parameter lists in function header in the same way as other languages. To pass data, assign variables in the calling scope before the call or use global vars as an explicit convention. To return values, write to a known variable. Keep this pattern disciplined and documented in your package header.
Recursion and repetition
Because Bolt lacks loop keywords (for/while), recursion or repeated calls are the structured way to perform repetition. Use recursion with caution: ensure a clear base case to avoid stack overflow. Example (conceptual):
# conceptual: use carefully
fn repeat_once();
sys.out 'repeating'
# conditionally call again
end
let.call repeat_once()
Common errors & fixes
Forward reference: If calling a function before it's defined, prefer let.call after the definition or move definitions earlier.
Missing return pattern: Document and use a named output variable to emulate return values.
Requirements & notes
Function declaration and let.call are standard in v1.61+. The function model is intentionally simple to keep runtime predictable and safe for distribution.
Capture user-provided values directly as specific types to avoid manual parsing and error-prone conversions. This reduces common input validation bugs.
Exact syntax
var = let.userinput.int 'prompt' - requests input and returns an integer. var = let.userinput.str 'prompt' - requests input and returns a string.
Examples
num = let.userinput.int 'enter a number: '
name = let.userinput.str 'enter your name: '
Validation & failure modes
If the user enters non-numeric text on let.userinput.int, the runtime should re-prompt or produce a clear error. Test this behavior.
If your runtime is older and lacks typed helpers, implement a parsing fallback: read raw input, validate with a numeric check, and re-prompt on failure.
Common errors & fixes
Non-numeric entry for int helper: Confirm whether runtime auto-validates; if not, implement a manual check loop using function calls and re-prompts.
Blocking prompts in automation: When using scripts in CI, provide flags or environment variables to bypass interactive prompts. See "Safe scripting practices" article for patterns.
Requirements
Typed helpers require Bolt v1.61+. For automation and installs, detect version via bolt --version and apply fallback logic where necessary.
Control Flow - if / eif / else
Purpose
Model conditional decision points. The control flow ladder is intentionally compact and readable: if begins a branch, eif chains additional conditions, and else handles the fallback. Close with end.if.
Exact syntax
if condition
...
eif other_condition
...
else
...
end.if
Condition rules
Conditions evaluate to truthy/falsey values per Bolt's runtime semantics. For numeric comparisons use explicit numeric variables and operators.
Type-check before numeric comparisons: if a condition mixes types, convert or use typed inputs to ensure correct evaluation.
Parentheses may be used for clarity where supported by the runtime.
No looping constructs
Bolt as documented in this reference does not provide built-in looping keywords (for, while, do/while). Where repetition is required, use function-based patterns and recursion with explicit base-case guards or perform external iteration in the calling environment (scripts that call Bolt multiple times or orchestrate repeated execution). And as of February 24th 2026 and bolt 1.61, Bolt does not provide any modules like random or others like python. We are working to add this feature very soon!
Examples & patterns
if /score/ >= 90
sys.out 'grade: A'
eif /score/ >= 80
sys.out 'grade: B'
else
sys.out 'grade: C or below'
end.if
Common errors & fixes
Type mismatch in comparison: Convert or validate operands. Fix: use typed inputs or tonumber().
Missing end.if: The block must be closed. Fix: add end.if at the correct indentation level.
Requirements & notes
Control flow is robust in v1.61+. Because there are no loop keywords, prefer small, testable functions for repeating behavior; this leads to clearer and more maintainable scripts for distribution.
Error handling & diagnostics
Purpose
Provide clear, reproducible failure messages and machine-readable diagnostics for automation and support workflows.
Best practices
Run with --debug for verbose tracebacks during development.
Use --json-errors when attaching logs to support tickets or CI systems.
When reporting issues, include: Bolt version (bolt --version output), the exact script, the terminal output, and the command-line flags used.
Common diagnostic patterns
bolt --debug --run script.blt
# or for CI:
bolt --json-errors --run script.blt
Compatibility & Version Detection
Purpose
Allow scripts to detect runtime capabilities and select typed helpers or fallback logic accordingly.
Pattern
# pattern (conceptual)
# 1) call `bolt --version` to detect runtime
# 2) branch in packaging to include fallbacks
Packaging recommendation
Distribute a small header in scripts that prints expected runtime and performs a capability check, followed by two code paths: typed-helpers-enabled (v1.61+) and fallback parsing. This keeps packages resilient across environments.
All deep reference code samples follow Bolt v1.61+ conventions. v1.70 adds modules, bytecode workflow, and the pre-baked libraries documented above. If you require a separate legacy compatibility appendix (v1.50 - v1.60), we can produce a compact fallback appendix that shows explicit parsing and error handling patterns.
Calculator Example - Full Breakdown (v1.61+)
The calculator example below assumes Bolt v1.61+ so that typed input helpers and modern control flow are available. The example is split into parts with precise, testable fixes and fallback suggestions for older runtimes.
Run bolt --version and confirm v1.61 or newer (v1.70 recommended for library support).
Enter valid integers and verify arithmetic results match expectations.
Try invalid inputs and confirm either the typed helper re-prompts or your parse fallback handles the case.
Check division by zero behavior and confirm the guard prints the error message.
If issues persist, gather the exact terminal output and the Bolt version and include them in your support request.
Examples
Small, copy-ready samples for quick testing on v1.61+ and v1.70 runtimes. Each example is accompanied by the exact expected output or failure mode so you can validate behavior.
# Save as hello.bolt
sys.out 'hello, world!'
bolt --inspect-ast --exec-string "sys.out '1+2'"
Module example (mymod.boltmodule)
public.module[mymod$1] {{
fn module_init();
sys.out 'mymod initialized'
end
fn greet();
sys.out 'hello from mymod'
end
}}
Using the module in a script (app.bolt)
$get.module mymod$1 $; m
let.call m.module_init()
let.call m.greet()
Articles
Short articles to help you design scripts for both interactive usage and automation. Each article includes concrete examples and support notes. The deep syntax reference is also linked from here for in-depth reading.
Safe scripting practices
Detect runtime version with bolt --version and choose typed helpers when v1.61+ is detected. For automation, avoid blocking user prompts; accept flags or environment variables to switch into noninteractive mode. Provide explicit error codes and, when applicable, --json-errors for CI consumers.
Distributing scripts
Include a small header that prints expected runtime version and usage. Provide both typed-helper paths for v1.61+ and fallback parsing code for earlier runtimes so your package runs across environments. For v1.70 distribute compiled .bvmb artifacts alongside source to support environments that prefer bytecode-only deployment. Keep the API surface minimal and document every exported variable and required runtime capability.
Troubleshooting
Concrete steps when Bolt is not recognized or scripts fail. No vague suggestions.
Bolt not recognized
Confirm install folder exists. Windows default: C:\Program Files\Bolt.
Run the executable directly from the folder: open PowerShell in the folder and run .\bolt --version. If this runs, the binary is fine but not on PATH.
Add the install folder to PATH:
Windows: Start → Edit the system environment variables → Environment Variables → under System variables edit Path → Add the Bolt folder → Save → restart terminal.
If the binary is missing or corrupt, re-download the installer from the official page and reinstall. Use the installer-provided uninstall when available before reinstalling.
Script errors or missing helpers
Confirm your runtime version is v1.61+ for typed helpers and modern control flow. For v1.70 features (modules, bytecode generation, pre-baked libraries), confirm the runtime reports v1.70+. If running older versions, include fallback parsing and safe guards. When requesting help provide the Bolt version, the script, and the exact terminal output.
Collect logs
Run scripts with bolt --debug --run script.bolt or bolt --json-errors --run script.bolt to get structured information to attach to a support request. For compiled artifacts, include both the source .bolt and compiled .bvmb files plus the exact compilation command used.
Legal & Credits
All rights reserved. Verify downloadable artifacts with the signed checksums on the official download page before installation.