CLI Reference

Everything you do with Cade goes through the cade command. This page is the reference for its subcommands and the flags that matter day to day. Every command also has built-in help:

cade --help            # list all commands
cade <command> --help  # flags and usage for one command

Global flags

These apply to every command:

Configuration precedence

Most settings can come from more than one place. Cade resolves them in this order (highest first):

1. A command-line flag
2. An environment variable — CADE_ plus the setting path in caps with _ for . (e.g. CADE_WEB_ENABLED, CADE_LOGGING_LEVEL)
3. The cade.conf file (HCL)
4. The built-in default

A few settings have no flag and are set only via cade.conf or the environment — for example game.max_players, game.balls_per_game, and game.credits_per_player.

Everyday commands

cade — run a table

Run with no subcommand to start the runtime. Cade loads the table, wires devices, scoring, modes, and event handlers, optionally starts the web server, and runs until you stop it (Ctrl-C).

cade -d ./my-table              # run the table in ./my-table
cade -d ./my-table -w           # also start the web server

With no platform block configured, Cade auto-starts a one-player headless game (handy for CI). With a platform block present, it waits for the hardware start button. Hardware and simulator connections are configured with platform "grpc" { … } blocks in your config, not with flags — see Drivers.

cade console — interactive console

Open the interactive TUI for debugging a live table — evaluate expressions, trigger events, inspect state, and watch event cascades. When stdin isn’t a terminal (or with --no-tui), it runs in scriptable pipe mode. See Console for the in-console commands and shortcuts.

cade console -d ./my-table
cade console -d ./my-table --start --autoplay   # hands-free demo

To drive the console from a simulator such as Visual Pinball X, use the gRPC flags (--grpc, --grpc-platform <addr>, --grpc-host, --grpc-port); --grpc-platform implies --grpc. See Visual Pinball and Migrating from Visual Pinball.

cade validate — check a config

Validate HCL syntax, required fields, types, references, circular dependencies, and variable formulas before you run.

cade validate                    # validate the current directory
cade validate my-table.cade      # validate one file
cade validate --strict --dir ./tables -r
cade validate --include-file-org # add advisory file-organization hints

File-organization hints

With --include-file-org, validation also runs an advisory linter that suggests how to lay out device, module, and variable blocks across files. Its findings are warnings only — they include a file:line and a suggestion, and they never make validation fail. They appear in text output and in the json/yaml formats alongside the other warnings. The linter flags:

• a device block in a file under modules/
• a module block in a file under devices/
• a file that mixes device and module blocks
• a top-level variable declared alongside module blocks
• a file longer than the recommended 500 lines

⚠ device block in a file under modules/  (modules/playfield.cade:12)
  → Move device definitions to devices/ or the config root

To silence these hints, add them to disable_checks in the file’s pragma block — disable_checks = ["file_organization"] turns the whole linter off for that file, or list an individual rule (such as "device_in_module_dir") to suppress just one.

cade scenario run — run tests

Run scenario tests (.cade.test files) against the real scoring engine. See Testing & Scenarios for writing them.

cade scenario run my-table.cade.test
cade scenario run ./tests -r --strict

cade version

Print the version, git commit, build time, Go version, and platform.

cade version

Configuration & migration

cade migrate — fix reserved-word conflicts

Find (and optionally rewrite) identifiers that collide with Cade’s reserved keywords. Without --auto-fix it’s a dry run that reports conflicts and exits non-zero — useful as a CI gate. With --auto-fix it rewrites identifiers and leaves .bak backups. See Reserved Keyword Validation.

cade migrate --reserved-words                 # dry run, report conflicts
cade migrate --reserved-words --auto-fix      # apply fixes (+ .bak backups)

cade pragma — inspect and migrate pragma modes

cade pragma analyze                          # show effective pragma settings
cade pragma migrate my-table.cade --target-mode strict          # preview
cade pragma migrate my-table.cade --target-mode strict --apply  # write

• cade pragma analyze [config-file] — show the effective pragma settings and their impact (--format text|json).
• cade pragma migrate <config-file> --target-mode <mode> — preview a move between strict / normal / relaxed; add --apply to write it.

Diagnostics

The diag subcommands inspect a config without running it. Each takes an optional [config-file] (default: current directory) and supports --format and --no-color.

cade diag deps --variable jackpot_value --format d2
cade diag perf --threshold 0.5

cade analyze [config-file] gives a combined validation-and-best-practice report (--verbose, --format, --no-suggestions, --ignore <pattern>).

History & replay

Cade can record game sessions and turn them into replays or scenario tests.

cade history list                            # list recorded sessions
cade history export --latest -o session.json # export the most recent
cade replay tree session.json                # print its event tree
cade replay to-scenario session.json --with-expectations -o regression.cade.test

• cade history list — list recorded sessions (--limit, --format table|ids, --db <path>).
• cade history export — export a session to JSON or event-stream (--session <id> or --latest, --output, --format json|event-stream).
• cade replay to-scenario <file.json> — convert a replay into a .cade.test (--output/-o, --ball, --scoring-only, --with-expectations).
• cade replay analyze <file.json> — summary report (--format text|json, --ball <n>); exits non-zero on error-level anomalies (CI gate).
• cade replay tree <file.json> — print the event tree, the plain-text mirror of the console’s event viewer (--ball <n>).

Most commands accept --format json (and several add yaml) for piping into other tools.