Configuration — Liu Terminal

Liu Terminal configuration. Customize themes, keybindings, fonts, and settings via JSON config file.

config.json lives at ~/.config/Liu/config.json. Keys are flat top-level strings and numbers (not nested objects). Liu loads it on launch and reloads automatically when the file changes on disk. Unknown keys are ignored.

File layout

~/.config/Liu/
├── config.json        # main app settings
├── keybindings.json   # custom keybindings (see Keybindings page)
├── known_hosts        # OpenSSH-format known hosts
├── vault.db           # AES-256-GCM encrypted SQLite vault (PBKDF2 key derivation)
└── themes/
    ├── my-theme.json
    └── ...

Top-level fields

theme string "Liu"

Active theme name. Must match one of the 18 built-ins or a JSON file in ~/.config/Liu/themes/.

font_path string "JetBrainsMono-Regular.ttf"

Primary font file. Bare filenames resolve against the bundled fonts directory; absolute paths work too.

font_size number 16

Point size before DPI scaling.

enable_ligatures boolean true

Toggle programming-ligature shaping.

cursor_style number 0

0 = block · 1 = underline · 2 = bar

cursor_blink boolean true

Blink in focused panes only.

scrollback number 1000

Lines per pane (clamped 0–20000). Memory grows with cols × scrollback.

vault_auto_lock_minutes number 15

Auto-lock vault after N minutes idle (0 = never).

quake_mode boolean false

Enable Quake-style slide-down window (requires quake_hotkey).

quake_hotkey string "Ctrl+`"

Global hotkey string when quake_mode is true.

Other supported keys

The table above shows the most commonly edited values. The loader also accepts these flat top-level groups:

  • line_height, font_normalize, font_smoothing, font_weight and fallback_font_0 … fallback_font_3 control font metrics and fallback fonts. Defaults: 1.0, true, true, 0; font weight is clamped to 0–2.
  • tab_sleep_idle_minutes defaults to 20; confirm_close_agent, bold_is_bright, show_scrollbar, show_tab_bar, show_toolbar_icons and show_git_badge default to true. bidi_enabled, hide_title_bar and show_status_bar default to false.
  • sidebar_width defaults to 240 and is clamped to 160–500; opacity defaults to 1.0 and is clamped to 0.2–1.0; padding defaults to 2.
  • browser_enabled, browser_last_url and browser_recent_0 … browser_recent_7 store browser state. The in-app browser is available on the macOS WebKit build.
  • option_as_alt accepts off, left, right or both; prompt_recall accepts off, badge or always. cursor_animate defaults to false, notify_command_threshold to 10, and allow_osc52_write to false.
  • background_image, notes_vault_path, background_mode (stretch/center/tile/fill), background_opacity, background_blur and background_blur_radius configure the image layer. The defaults are empty path, empty path, fill, 0.3, false and 10.
  • quake_mode, quake_hotkey, quake_height_ratio and quake_animation_duration default to false, Ctrl+`, 0.4 and 0.2; their numeric ranges are 0.1–1.0 and 0–10.
  • profile_count plus profile_<index>_name, _font_path, _font_size, _theme, _cursor_style and _opacity define up to 16 profiles. Translate-on-Tab and Voice keys are documented on their dedicated pages.
  • site_count plus site_<index>_name, _path, _command and _port define up to 32 Site Manager entries; runtime process state is not persisted.

The persisted style keys are style_tab_gap, style_tab_dot_size, style_tab_close_size, style_tab_close_margin, style_tab_indicator_height, style_status_bar_height, style_sidebar_default_width, style_sidebar_min_width, style_sidebar_max_width, style_sidebar_header_height, style_terminal_padding, style_terminal_top_gap, style_active_pane_indicator_thickness and style_active_pane_indicator_color (an r,g,b,a string). Toolbar height and tab width are compile-time layout constants, not configurable keys.

Example

{
  "theme": "Tokyo Night",
  "font_path": "JetBrainsMono-Regular.ttf",
  "font_size": 14,
  "enable_ligatures": true,
  "cursor_style": 2,
  "cursor_blink": false,
  "scrollback": 5000,
  "vault_auto_lock_minutes": 30,
  "quake_mode": true,
  "quake_hotkey": "Ctrl+`"
}

Tab count is hard-capped at 32 per window (MAX_TABS in src/ui/ui.h) — not configurable here. GPU backend is chosen at compile time (Metal on macOS, OpenGL elsewhere). Numeric fields like scrollback are clamped to safe ranges on load.

Back to Introduction ↺

Documentation

Getting started

Guides

Reference

Other languages

Türkçe · 简体中文 · 한국어 · Español · Deutsch · Italiano · Français · 日本語 · العربية