FLI Reference

FLI (fli.exe) is the FCS Language Interpreter command-line tool. It is one of the most important tools for inspecting models, evaluating expressions, generating outputs, and supporting AI-assisted workflows.

This guide ranks the available modes by usefulness for iterative development and agent-driven exploration.

Recommended Usage Order

  1. --i-json REPL — best for iterative work
  2. --list-members — best for quick discovery
  3. 2-arg mode — best for simple one-off evaluation
  4. 3-arg mode — best for evaluation with overrides
  5. Interactive console — useful, but requires a real TTY
  6. Output generation — for producing scene/image/report artifacts

1. --i-json REPL (Best for Iterative Work)

fli.exe --i-json model.fcs

This is the most powerful mode for repeated inspection because it keeps a persistent session open and accepts JSON commands line by line.

Why it is best

Supported JSON commands

{"ls":""}

List all members.

{"ls":"subexpr"}

List members of a sub-expression.

{"expr":"<expression>"}

Evaluate an expression.

{"expr":"...","updater":"{param=val}"}

Evaluate with an override/updater.

{"reload":true}

Reload files from disk.

Typical session flow

fli.exe --i-json model.fcs

Then send JSON lines such as:

{"ls":""}
{"expr":"width"}
{"expr":"area"}
{"expr":"roofHeight","updater":"{span=12}"}
{"reload":true}

Gotcha: first line may not be JSON

The first line can be a non-JSON engine warning. If you are scripting against this mode, filter out lines that do not start with {.

Practical tip: when building wrappers around --i-json, treat each output line independently and ignore banner/warning text before parsing JSON.

2. --list-members (Quick Discovery)

fli.exe --list-members model.fcs

This returns JSON describing the available members, values, and types in the model.

Best use cases

Strengths

Limitation

It is a snapshot, not a persistent session.

Practical tip: start with --list-members when you inherit an unfamiliar .fcs file and want to know what names are available before evaluating expressions.

3. 2-Arg Mode (Simple Evaluation)

fli.exe model.fcs "expression"

This is the easiest way to evaluate a single expression.

Example

fli.exe model.fcs "area"
fli.exe bridge.fcs "mainSpan"

Characteristics

Best use cases

4. 3-Arg Mode (Evaluation with Updater → Proxy JSON)

fli.exe model.fcs "expression" "{param=value}"

This mode evaluates an expression using an updater override and returns a proxy JSON object.

Example

fli.exe model.fcs "area" "{width=12,height=8}"

Return shape

{"Content":...,"Exception":...}

Best use cases

Practical tip: prefer this mode over manual file edits when exploring "what if" scenarios.

5. Interactive Console

fli.exe model.fcs

This launches the classic interactive console.

Important limitation

It requires a real TTY and fails in non-interactive shells.

That makes it less reliable for automation, CI, and many agent environments.

Common commands

When to use it

Use this mode when you are working directly in a local terminal and want a human-driven interactive experience.

When not to use it

Avoid it in wrappers, background processes, or non-interactive environments. Prefer --i-json instead.

6. Output Generation

FLI can generate outputs from expressions.

fli.exe model.fcs "expr" --t 3JS --o scene.json    # HiScene JSON (3D)
fli.exe model.fcs "expr" --t PNG --o image.png      # Image
fli.exe model.fcs "expr" --t HTML --o report.html   # Report
fli.exe --dump-scene model.fcs --o scene.json       # Scene dump

Common output scenarios

Practical tip

Use an explicit output filename with --o so downstream tools know exactly where to find the generated artifact.

Common Flags

--td Warning

Show diagnostics at warning level.

fli.exe --td Warning model.fcs "area"

Use this when you want visibility into warnings without switching to a noisier diagnostic level.

--fcs <path>

Use an absolute path.

fli.exe --fcs "D:\Models\sample.fcs" "area"

Gotcha

Relative paths can trigger a path-doubling bug. Prefer absolute paths consistently.

--i-json

Enables JSON REPL mode.

fli.exe --i-json model.fcs

Example Workflows

Workflow: discover then evaluate

fli.exe --list-members model.fcs
fli.exe model.fcs "mainSpan"
fli.exe model.fcs "roofArea"

Workflow: iterate with reload

fli.exe --i-json model.fcs

Then:

{"ls":""}
{"expr":"mainSpan"}
{"reload":true}
{"expr":"mainSpan"}

Workflow: test overrides safely

fli.exe model.fcs "roofHeight" "{span=18,pitch=30}"

Workflow: generate a scene artifact

fli.exe model.fcs "building" --t 3JS --o scene.json

AI-Agent Practical Guidance

If you are scripting FLI or driving it from an agent:

Common Gotchas

Quick Reference

# Best iterative mode
fli.exe --i-json model.fcs

# List members
fli.exe --list-members model.fcs

# Evaluate one expression
fli.exe model.fcs "expr"

# Evaluate with updater
fli.exe model.fcs "expr" "{param=value}"

# Generate output
fli.exe model.fcs "expr" --t 3JS --o scene.json
fli.exe model.fcs "expr" --t PNG --o image.png
fli.exe model.fcs "expr" --t HTML --o report.html

# Dump scene
fli.exe --dump-scene model.fcs --o scene.json

Final Recommendation

For most onboarding, debugging, and agent-assisted work, start with:

  1. --list-members to discover the model surface
  2. --i-json to inspect and iterate quickly
  3. 3-arg mode when you need controlled parameter overrides