Installation & CLI Reference

Flame provides an all-in-one developer workspace toolchain containing a compiler, an Ahead-of-Time (AOT) builder, an automated code formatter, diagnostics engine, and zero-overhead native FFI bridging capabilities.

---

Installation

Install the Flame toolchain globally using your preferred package manager:

cargo

cargo install --force flamelang

npm

npm install -g flamelang

pnpm

pnpm add -g flamelang

yarn

yarn global add flamelang

bun

bun add -g flamelang

---

Verifying the Installation

Check that flame (or flamelang) is accessible from your terminal:

flame --version

To view the complete help menu and all available flags:

flame --help

---

Project Structure & Manifest

A standard Flame project contains a flame.toml manifest file and source code in src/:

my-flame-app/
├── flame.toml           # Project manifest, native crates & plugins
└── src/
    └── main.fm          # Application entrypoint

Manifest Example (flame.toml)

[package]
name = "my_flame_app"
version = "0.1.0"
entry = "src/main.fm"

[native-dependencies]
uuid = { version = "1.0", features = ["v4"] }
axum = "0.7"

[plugins]
server = "./native"

Just like a normal Cargo.toml, users can configure native crate features and version specifications manually by editing flame.toml.

---

CLI & Toolchain Reference

The flame binary provides a unified command set for your entire development workflow:

1. Running & Building Applications

⚡ Quick-Run (flame)

Inside any Flame project directory (where flame.toml is present), simply type flame and press enter to instantly compile and run your application entry point:

flame

flame run

Runs the Flame entry file main.fm:

flame run

flame build

Compiles your Flame application and its native Rust bridges into a standalone executable:

# Debug build in target/dev/
flame build

# Release build in target/release/
flame build --release

Release Optimizations

flame build --release configures LLVM for maximum performance:

• Full optimization (opt-level = 3)
• Fat Link Time Optimization (lto = "fat")
• Single code generation unit (codegen-units = 1)
• Stripped symbol tables (strip = true)
• Zero-overhead aborting panics (panic = "abort")
• Automatic stripping of all @Test, @Setup, and @Cleanup test fixtures!

---

2. Package & Native Plugin Management

flame new <name>

Initializes a new Flame workspace directory with a starter manifest and directory structure:

flame new my_app

flame add <url_or_name>

Downloads and registers external Flame modules or packages:

flame add https://github.com/example/flame-package

flame add <crate_name> --native

Adds a Rust crate as a native dependency under [native-dependencies] in your flame.toml:

flame add uuid --native

Just like a normal Cargo.toml, users can configure crate features manually by editing flame.toml:

[native-dependencies]
uuid = { version = "1.0", features = ["v4"] }

flame native init [plugin_name]

Scaffolds a native Rust plugin workspace (./native) inside your current project. It creates a starter Cargo.toml, bridge boilerplate code, and automatically registers the plugin in your flame.toml:

flame native init server

flame add --plugin <path_to_plugin> [--name <plugin_name>]

Registers an existing local or external native Rust plugin inside your flame.toml manifest. If --name is omitted, Flame automatically discovers the plugin name from its Cargo.toml or folder name:

# Register using flag
flame add --plugin ./native --name server

---

3. Diagnostics & IDE Integration (check --json)

flame check <file.fm> [--json] [--line N --col N]

Performs instantaneous syntactic analysis, type inference, and static diagnostics without compiling or linking binaries.

When invoked with --json, it emits structured metadata designed for IDEs and the Language Server Protocol (LSP):

• Precision Hover Metadata: Passing --line N --col N resolves the exact AST symbol under the cursor, returning inferred primitive types, native .fmi struct signatures, and identifying native AOT packages as plugin (e.g. server: plugin).
• Autocomplete & IntelliSense: Extracts methods, parameters, docstrings, and struct layouts from standard libraries (std.*) and native plugins (native.*).
• Real-Time Diagnostics: Emits syntax errors, undefined symbols, and type mismatches with exact line and column numbers.

Example Command & JSON Payload

flame check automation/src/main.fm --json --line 47 --col 18

{
  "file": "automation/src/main.fm",
  "diagnostics": [],
  "std_modules": ["thread", "process", "fs", "math", "time", "os", "env"],
  "native_modules": ["server"],
  "plugins": [
    {
      "name": "server",
      "source": "./native",
      "version": null,
      "is_local": true
    }
  ],
  "completions": [],
  "hover": {
    "label": "server",
    "documentation": "```flame\nserver: plugin\n```\nInferred type from AST"
  }
}

---

4. Code Formatting

flame format <file.fm>

Automatically formats your source code to adhere to Flame’s canonical style rules:

# Format a specific file and write changes
flame format src/main.fm

# Output formatted code to stdout without writing
flame format src/main.fm --stdout

flame format --all

Formats all .fm source files across your entire project workspace:

flame format --all
# or simply:
flame format

---

5. Native Test Runner

flame test

Discovers and executes all @Test annotated functions across your project files:

flame test