Command Reference

The Cade Console provides commands for expression evaluation, event simulation, variable management, engine control, gameplay simulation, and debugging.

Type help for the built-in list, or help <command> for detail on one. help -i opens an interactive browser you navigate with arrow keys, search with /, and drill into with Enter.

Command Summary

step and continue also accept the short forms s and c; breakpoint accepts break, and watchpoint accepts wp.

Expression Evaluation

eval evaluates an expression against the variables in the current session. Reference variables bare — var.score, not ${var.score}:

cade:debug> eval 100 + 50
Result: 150

cade:debug> eval var.score * 2
Result: 2000

cade:debug> eval var.score + (var.bonus.multiplier * 500)
Result: 2500

cade:debug> eval var.score > 1000 && var.multiball.active
Result: false

Pass extra variables inline without setting them:

cade:debug> eval var.x + var.y --vars x=10,y=20
Result: 30

The console evaluator is a compact calculator — arithmetic, comparison, logic, and min/max/abs. See Expressions for the exact surface, and Writing Expressions for the richer language your .cade files use.

Event Triggering

trigger fires events into the scoring engine — both named scoring events and hardware switches. Extra parameters are given as key=value pairs:

cade:debug> trigger target.hit
Event: target.hit
Player: 1
Total points: 500
New score: 1500

cade:debug> trigger target.hit points=500 multiplier=2
cade:debug> trigger switch.ramp_entry

When an event is triggered the console captures the resulting cascade. Press F7 to view it, or run cascade last.

Variable Management

Setting

cade:debug> set var.score 1000
Set var.score = 1000 for player 1

cade:debug> set var.bonus.multiplier 3
cade:debug> set var.multiball.active true

Values are parsed as integer, then float, then boolean, then string — so true becomes a boolean and 1000 an integer.

Inspecting

inspect shows detail about a variable or event, auto-detecting which you meant. Switch output format with --json or --hcl:

cade:debug> inspect score
Variable: score
Type: int
Scope: player
Current value: 1,000
Initial value: 0

cade:debug> inspect vars              # list all variables
cade:debug> inspect events            # list all events
cade:debug> inspect events --live     # recent live events from the hardware bridge
cade:debug> inspect bumper.hit        # inspect as event: triggers, conditions, actions
cade:debug> inspect score --json

Watching

cade:debug> watch var.score
Now watching variable: var.score

[WATCH] var.score changed from 1000 to 1500 for player 1

cade:debug> unwatch var.score
Stopped watching variable: var.score

Player Management

cade:debug> player
Current player: 1

cade:debug> player 2
Active player set to: 2

Simulating a Game

coin, start, and go reproduce the front-of-machine sequence without hardware — useful for exercising attract mode, credits, and multiplayer flow.

cade:debug> coin
Credit! Balance: 1

cade:debug> start
Player 1 joined. Press 'start' to add more players, or 'go' to begin.

cade:debug> start
Player 2 joined. Press 'start' to add more players, or 'go' to begin.

cade:debug> go
Game started with 2 player(s): [Player 1 Player 2]

coin grants credits per your coins_per_credit setting — with a value above 1 the console reports Coin accepted (accumulating) until a full credit lands. Each start consumes a credit and queues one more player, up to the configured maximum; start also works mid-game to join a player late. go launches with everyone queued and puts the first ball in play.

Engine Control

cade:debug> engine start
✓ Engine started

cade:debug> engine pause
cade:debug> engine resume
cade:debug> engine restart
cade:debug> engine reload      # re-read the table configuration
cade:debug> engine stop
cade:debug> engine status

engine status reports state, running and paused flags, and engine metrics. engine start and engine restart verify the engine actually came up and report the underlying error if it did not — most often a missing or invalid table configuration.

Configuration

Load a table:

cade:debug> load my-game.cade

Save your live console settings so they persist across sessions:

cade:debug> config save
✓ Console config saved to /home/you/.cade_console_config.hcl

cade:debug> config save ./my-console.hcl

The path must end in .hcl. The written file round-trips through the loader unchanged, so it is also a good starting point to hand-edit. See Configuration.

Reload the console configuration without restarting:

cade:debug> reload           # reload and show what changed
cade:debug> reload config    # reload
cade:debug> reload status    # config path, version, last reload time
cade:debug> reload diff      # compare loaded config against disk, without applying

Querying Game History

With no arguments, history lists your recent commands. With a subcommand it queries the recorded game history database — a full record of past sessions, scores, and cascades.

cade:debug> history games 5
cade:debug> history scores
cade:debug> history ball 12 "Player 1" 3
cade:debug> history sql "SELECT name, COUNT(*) FROM switch_hits GROUP BY name"

Profiler

profile controls the scoring profiler, which tracks event and expression evaluation performance.

cade:debug> profile start
Profiling started

cade:debug> profile status
Scoring profiler: ACTIVE
  Event types tracked: 12
  Expression types tracked: 8

  Top events by P95 latency:
    bumper.hit                                P95:       45.2 us

cade:debug> profile export ./my-profiles/
Profile exported to: ./my-profiles/scoring_profile_20250315_143022.json

cade:debug> profile stop
cade:debug> profile reset

Scenario Testing

scenario runs predefined test scenarios against the scoring engine.

cade:debug> scenario list
cade:debug> scenario run tests/basic_scoring.yaml
cade:debug> scenario run --all tests/
cade:debug> scenario status
cade:debug> scenario warp tests/multiball_setup.yaml

warp loads a scenario’s initial state without running its assertions — a fast way to reach a complex game state for manual testing.

You can also play a scenario straight into the live event tree at launch:

cade console --scenario tests/multiball.cade.test

Session Information

cade:debug> status
Debug Session Status
==================
Active Player: 1
Total Players: 4
Variables Set: 3
Watched Variables: 1 (score)
Commands Executed: 15

Tab Completion

Completion is context-aware — commands, variables, event names, and subcommands:

cade:debug> he<Tab>
help     history

cade:debug> set var.bo<Tab>
var.bonus.active    var.bonus.multiplier    var.bonus.value

cade:debug> trigger tar<Tab>
target.hit    target.dropped    target.raised

cade:debug> history q<Tab>
query    queries

Running Commands from Scripts

Every command also works in Pipe mode, where the console reads one command per line from stdin instead of showing the TUI:

cat <<'EOF' | cade console
# lines starting with '#' are comments and are skipped
set var.score 1000
set var.bonus.multiplier 3
eval var.score + (var.bonus.multiplier * 500)
inspect score
exit
EOF

Pipe mode activates automatically when stdin is redirected, or force it with --no-tui. Results print to stdout, so you can filter them with standard tools:

echo "inspect score" | cade console --no-tui | grep "value"

The console returns a non-zero exit code when a command fails, so scripts and CI jobs can detect problems. See Exit Codes.