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:

1. ~/.cade/console.hcl
2. ./.cade-console.hcl (in the working directory)
3. ~/.cade_console_config.hcl

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.

Important: Every block below except session is required, as are the nested score_format and custom blocks. A file that omits one fails to load with Missing <name> block. Include empty blocks rather than dropping them:

colors {
  enabled = true
  scheme  = "default"

  custom {}
}

Individual attributes are 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"
    use_thousand_separator = true
    thousand_separator     = ","
    abbreviate             = false
  }
}

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. This block is required, but every attribute defaults to empty — the renderer falls back to comma formatting when you leave them unset.

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.