Configuration

The console reads its settings from an HCL file that controls the prompt, history, display, colors, completion, startup commands, and session behavior.

You can write this file by hand, or capture your live settings from inside the console with config save.

File Location

On startup the console looks for, in order (earlier entries win):

1. ./.cade-console.hcl (project-local, relative to the working directory)
2. ~/.cade_console_config.hcl (the per-user default, and where config save with no argument writes)
3. ~/.cade/console.hcl (a third, older location — kept but not preferred)

Point it somewhere else with --console-config:

cade console --console-config ./my-console.hcl

Only .hcl is supported — any other extension is rejected. config save with no path writes ~/.cade_console_config.hcl.

Every block below, including the nested score_format and custom blocks, is optional — omit a block entirely and it keeps every one of its defaults, the same as omitting an individual attribute inside a block you do write. A file with just a prompt {} and a history {} loads cleanly; nothing fails with a missing-block error.

Individual attributes within a block you do write are likewise optional — anything you leave out keeps its default.

Note: This file is plain HCL data. Unlike .cade table files it is evaluated without variables, locals, or functions, so var., local., and env() do not work here — write literal values.

Example

prompt {
  format              = ""
  show_player         = true
  show_watched_count  = true
  show_variable_count = true
  prefix              = "cade"
  suffix              = "> "
}

history {
  enabled               = true
  file_path             = ""
  max_entries           = 1000
  save_on_exit          = true
  ignore_duplicates     = true
  ignore_space          = false
  case_sensitive_search = false
}

display {
  show_welcome     = true
  show_goodbye     = true
  output_format    = "normal"
  show_timestamps  = false
  timestamp_format = "15:04:05"
  clear_on_startup = false

  score_format {
    style              = "commas"
    thousand_separator = ","
  }
}

colors {
  enabled = true
  scheme  = "default"

  custom {}
}

completion {
  enabled           = true
  case_sensitive    = false
  show_descriptions = true
  max_suggestions   = 20
  use_optimized     = true
}

startup {
  commands = [
    "watch var.score",
  ]
  scripts           = []
  default_player    = "debug"
  auto_load_session = false
}

session {
  auto_save          = false
  auto_save_interval = 300
  auto_restore       = false
  session_dir        = ""
  save_output        = true
  max_output_lines   = 1000
}

debug {
  enabled            = false
  tui_enabled        = false
  tui_log_path       = "/tmp/tui_debug.log"
  performance_timing = false
  verbose            = false
}

Options Reference

Prompt

format accepts these placeholders:

History

max_entries must not be negative; values below 10 or above 10000 load but warn. If you set file_path, its parent directory must already exist.

Display

Score Format

Nested inside display, and itself optional — omit it and scores render as comma-grouped.

custom_format takes a format of %[flags][width][.precision]verb, with two verbs — d for a plain integer and a for SI-abbreviated (1.2M) — and flags , (comma grouping), 0 (zero-pad), + (always show sign), and - (left-justify):

display {
  score_format {
    style         = "custom"
    custom_format = "%012,d"   # zero-padded to 12 digits, with commas
  }
}

Other examples: %d (plain), %,d (comma-grouped), %.1a (abbreviated to one decimal). Setting custom_format without style = "custom" loads fine but is ignored with a warning; style = "custom" with an empty or unparseable custom_format is a load error.

Colors

These control the console’s own output colors, independent of the TUI theme.

The nested custom block sets individual colors, used when scheme = "custom". Each value must be an ANSI escape sequence:

colors {
  enabled = true
  scheme  = "custom"

  custom {
    error   = "\033[91m"
    success = "\033[92m"
    warning = "\033[93m"
  }
}

Available keys: command, keyword, string, number, variable, operator, error, success, warning, info, prompt, player.

Tip: The solarized and monokai schemes set every color except operator, which keeps the default. Set operator explicitly under a custom scheme if that matters to you.

Completion

Values below 5 or above 100 for max_suggestions load but warn.

Startup

Startup commands are screened — entries containing rm , del , format, dd , or mkfs are rejected.

Session

The only optional block.

Debug

Command History

History is written to ~/.cade_debug_history unless history.file_path says otherwise. It loads on startup and saves on exit when save_on_exit is enabled; max_entries caps it, trimming oldest-first.

The history command with no arguments lists recent commands:

cade:debug> history 5

See Querying Game History for its subcommands, which query recorded games rather than typed commands.

Hot Reload

The console watches its config file and reapplies changes without a restart. Saves are debounced by 500 ms, so rapid edits coalesce into one reload.

Every reload is validated first. If the new file is invalid, the console keeps the previous config and reports:

⚠️  Config reload failed: <error> (keeping previous config)

These are preserved across a reload:

• The active player
• Watched variables and watched expressions
• Variables you have set

Colors, display settings, completion, and history are rebuilt immediately. Prompt changes appear at the next prompt.

Trigger a reload or inspect its state by hand:

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

Note: Hot reload only runs when a config file exists at one of the searched paths. Without one, reload reports hot reload is not enabled (no config file found) — create the file (easiest via config save) and restart.