Interactive Terminal and REPL

LuCLI includes a full interactive terminal with history, completion and a builtā€‘in CFML REPL (readā€“evalā€“print loop). This page explains how to start it and what you can do inside it.

Starting the interactive terminal

You can start the terminal in a few equivalent ways:

# If using the JAR directly
java -jar lucli.jar

# If using the binary
lucli

# Explicitly request terminal mode
lucli terminal

If you run java -jar lucli.jar or lucli without arguments, LuCLI automatically starts the interactive terminal. Youā€™ll see a banner similar to:

šŸš€ LuCLI Terminal x.y.z  Type 'exit' or 'quit' to leave.
šŸ“ Working Directory: /path/to/current/dir

From here you can run all the usual LuCLI commands (server, modules, etc.) plus a set of terminalā€‘only commands.

CFML REPL with cfml <expression>

The simplest REPL feature is the inline CFML expression command:

cfml now()
cfml 1 + 2
cfml dateFormat(now(), 'yyyy-mm-dd')

Behaviour:

  • The first time you use cfml, LuCLI initializes the Lucee engine for this terminal session.
  • Each cfml command wraps your expression in a small CFML template that prints the result.
  • Output is written directly to the terminal; complex values use Luceeā€™s standard display.

If you forget to pass an expression:

cfml

LuCLI responds with a helpful error and a usage hint.

Tip: use the terminal for quick experiments while developing modules or scriptsā€”no need to create a file for every small check.

Using LuCLI commands inside the terminal

Everything you can do from the normal CLI is also available in the terminal. For example:

# Server management
server start
server status
server log --follow

# Module management
modules list
modules run my-module arg1 arg2

# CFML command-line helpers
cfml 'now()'

Under the hood, the terminal delegates these to the same Picocli commands used in oneā€‘shot mode, so behaviour and options stay consistent.

File system commands & working directory tracking

The terminal includes a small set of builtā€‘in commands that behave like familiar shell tools but operate through LuCLIā€™s FileSystemState, so the current working directory is tracked consistently across commands:

  • Navigation: cd, pwd
  • Listing: ls, dir
  • Files & directories: mkdir, rmdir, rm, cp, mv, touch
  • Viewing content: cat, head, tail
  • Searching: find, wc
  • UI helpers: prompt (manage themes), edit (open files via configured editor)

Examples:

# Check where you are
pwd

# Change directory relative to current working directory
cd src
ls

# Create and inspect files
touch notes.txt
cat notes.txt

# Search for CFML files
find . *.cfs

The current working directory is also shown in the prompt (see Prompt & UI Customization).

History and completion

The terminal is built on JLine3 and provides a modern interactive experience:

Command history

  • Press ā†‘ / ā†“ to move through previous commands.
  • History is persisted between sessions in ~/.lucli/history.
  • Blank lines are not added to history.

This makes it easy to repeat or tweak previous cfml, server, or module commands.

Tab completion

Press Tab to get completions for:

  • Topā€‘level commands (server, modules, cfml, terminal, etc.)
  • Subcommands (start, stop, status, list, run, ā€¦)
  • Options and flags (such as --version, --port, --env)
  • File paths for many fileā€‘oriented commands

Completions come from a combination of Picocliā€™s command metadata and LuCLIā€™s own terminal completer.

Prompt, colours and emoji

The terminal prompt is themeable and emojiā€‘aware:

  • Themes are managed with the prompt command (for example prompt zsh, prompt minimal).
  • LuCLI detects whether your terminal supports emoji and falls back to text symbols when needed.
  • Status symbols (success, error, info) in many messages adapt to your terminal capabilities.

For full details and theme customization, see Prompt & UI Customization.

Exiting and interrupts

You can leave the terminal in several ways:

exit
quit

Or via control keys:

  • Ctrl+D ā€“ send EOF, which cleanly exits the terminal.
  • Ctrl+C ā€“ interrupt the current command; LuCLI prints ^C and returns you to the prompt without closing the session.

On exit, LuCLI closes the terminal and returns you to your normal shell.