Console Overview

The Cade Console is an interactive REPL (Read-Eval-Print Loop) for debugging and testing the Cade scoring system. It provides real-time inspection of game state, expression evaluation, event triggering, and variable monitoring.

Operating Modes

The console operates in three modes, selected automatically based on terminal capabilities.

TUI Mode

The default mode when running in an interactive terminal. TUI mode provides a full Terminal User Interface with tabbed views, real-time monitoring, tab completion, command history, and color output.

cade console
cade console -d ./my-table/

The console loads every .cade file in the table directory — --table-directory (-d), defaulting to the current directory.

Pipe Mode

The console automatically detects piped input and switches to a non-interactive mode suitable for scripting and automation. Pipe mode activates when stdin is a pipe or file rather than a terminal, or when you pass --no-tui to force it even from an interactive terminal.

echo "eval 2+2" | cade console

cat <<'EOF' | cade console
set var.score 1000
eval var.score * 2
exit
EOF

cade console < my_debug_script.txt

echo "inspect score" | cade console | grep "Value:"

In pipe mode the console reads one command per line from stdin, runs each in order, and prints results to stdout. It is built for scripted debugging and automation:

• Automatic detection — no flag is needed when input is piped or redirected; the console notices stdin is not a terminal and switches modes. Use --no-tui to force pipe mode from an interactive terminal.
• One command per line — each line is a complete command. Blank lines and lines beginning with # are ignored, so scripts can be commented.
• Clean exit — end the script with exit (or quit), or let it terminate at end-of-input (EOF). Colors are disabled so downstream tools receive plain text.
• Pipeline friendly — output flushes after each command, so you can pipe results into grep, awk, or any other tool.

Exit Codes

Pipe mode returns standard exit codes so scripts and CI jobs can detect failures:

# Fail a CI step if the debug script hits an error
cat checks.debug | cade console || echo "debug script failed with code $?"

Fallback Mode

When the terminal does not support the full TUI, the console falls back to basic line-editing mode. Fallback is triggered when:

• The TERM environment variable is set to dumb
• No TTY is available (pipes, Docker without -t, SSH without PTY)
• The CI environment variable is true
• The terminal does not support required capabilities

In fallback mode, basic line editing is available but cursor movement within the line, tab completion UI, color output, and Ctrl+R history search are not.

Mode Comparison

Terminal Compatibility

Full Support

• Linux – Complete readline with all features in modern terminal emulators (Alacritty, Kitty, GNOME Terminal, Konsole)
• macOS – Full support in Terminal.app and iTerm2
• Windows 10+ – Full support in Windows Terminal

Platform Notes

• On Windows, use Home/End instead of Ctrl+A/Ctrl+E and Ctrl+Left/Ctrl+Right for word navigation.
• On macOS, Meta key combinations may conflict with system shortcuts.

Launching the Console

# Load the .cade files in the current directory
cade console

# Load a specific table directory
cade console -d ./my-table/

# Start the scoring engine immediately on launch
cade console --start

# Force pipe mode (disable the TUI)
cade console --no-tui

Flags

Connecting to a platform such as Visual Pinball uses the gRPC flags:

Note: The global --config flag points at Cade’s own runtime config file, not at a table. Use -d to choose a table directory, or the load command once the console is running.

Once launched, the console displays the prompt:

cade:debug>

Type help for available commands or press Tab for completions.