^ ^                 ^ ^
=(o.o)=  ~byakuren  =(o.o)=
  m m                 m m

Flowlog CLI and REPL (flowlog.c)

This document describes the Flowlog command-line interface and REPL behavior for the binary built from flowlog.c.

The Flowlog binary is:

• ./flowlog

CLI usage

Show help:

./flowlog --help

Show version:

./flowlog --version

Interactive REPL (default)

Empty program:

./flowlog

Load a program and enter REPL:

./flowlog program.pl

You can also use the explicit file flag:

./flowlog -f program.pl

Run a one-shot query

./flowlog program.pl -g "goal."

Query against an empty program:

./flowlog -g "goal."

Thread count

Override the worker-thread count:

./flowlog --threads 12 program.pl -g "goal."

Aliases accepted by the binary:

• --threads
• --cpus
• --cpuprocs

Engine selection

Select the execution engine:

./flowlog --engine wamvm program.pl -g "goal."

Values:

• wamvm — default bytecode VM for compiled clause bodies (still sharing the same unifier/built-ins as wam); falls back to wam when the program/query uses unsupported features (see WAM_ROADMAP.md)
• wam — WAM-lite engine (falls back to the interpreter if needed)
• interp / tree — direct interpreter (“tree-walking”)

If wam or wamvm is requested but Flowlog falls back to the interpreter, it prints a warning to stderr by default. Disable this warning with:

• FLOWLOG_WARN_ENGINE_FALLBACK=0

To ensure the wamvm engine does not fall back to the WAM-lite solver for unsupported programs/queries, set:

• FLOWLOG_WAMVM_REQUIRE_VM=1 (exits with code 2 if unsupported built-ins are used)

You can also introspect which engine actually ran a query:

?- current_prolog_flag(flowlog_engine_active, Engine).

Parallel profile

Select a parallelism profile (equivalent to set_prolog_flag(flowlog_parallel_profile, ...)):

./flowlog --parallel-profile fast program.pl -g "goal."

Values:

• off — sequential behavior (Flowlog parallel features disabled)
• iso — enable parallelism but keep ordered solution commit
• fast — enable all parallel features and allow unordered OR-par for maximum throughput

Defaults (unless your program overrides flags with :- set_prolog_flag/2 directives):

• engine: wamvm
• profile: fast

REPL behavior

Prompts and non-interactive mode

• If stdin/stdout are a TTY, Flowlog prints a banner and a ?- prompt.
• If stdin/stdout are not a TTY, Flowlog reads from stdin without prompts/banners (useful for scripting).
• Ctrl‑C interrupts the current query and returns to the prompt (the loaded program remains in memory).
• Ctrl‑T (BSD SIGINFO) prints a live status report (current predicate, stack, parallel state, memory counters).

Meta-commands

The REPL supports a small set of meta-commands (single-line, no trailing . required):

• :help
• :load <file.pl>
• :reload (reload last loaded program)

And the ISO-style “regular” commands:

• help.
• halt. / quit.

Loading code interactively

The REPL supports the common Prolog top-level convenience:

• [file]. (and [file1,file2].) — load one or more source files (consult-style); this replaces the currently loaded program, similar to :load.

Use one of:

• Start the REPL with a file argument: ./flowlog program.pl
• :load program.pl (replaces the currently loaded program)
• :reload (reload the last :load file)

Output format

Flowlog prints output in a stable, test-friendly format:

• Each solution on its own line: X = 1, Y = foo
• Success with no bindings: true
• Failure: false

Environment variables

History

• FLOWLOG_HISTORY_FILE — history file path (TTY REPL only)
  • Default: ~/.flowlog_history

Parallelism tuning

• FLOWLOG_N_CPUPROC — default worker-thread count
• FLOWLOG_ORPAR_MAX_WORKERS — cap internal OR-par pthread workers
• FLOWLOG_ORPAR_STACK_SIZE — override OR-par pthread stack size (bytes)
• FLOWLOG_POOL_LOCAL_ALLOC — prefer process-local allocations for query-temporary memory (can improve OR-par scalability)

Debugging OR-par

• FLOWLOG_DEBUG_ORPAR — 0/off, 1 (big choicepoints), or 2/all
• FLOWLOG_DEBUG_ORPAR_LOG — file path to append OR-par debug logs

Exit codes

• 0 — success
• 1 — load or runtime failure
• 2 — CLI usage / argument errors