{{tag>[cli terminal multiplexer ai agent herdr config toml]}}

====== Herdr configuration ======
Herdr의 ''config.toml'' 위치, key, keybinding, theme, notification, reload와 검증 방법.

===== Summary =====
  * Herdr는 config file 없이도 실행되며, 필요할 때 TOML 파일을 추가한다.
  * Linux/macOS 기본 경로는 ''~/.config/herdr/config.toml'', Windows는 ''%APPDATA%\herdr\config.toml''이다.
  * 전체 기본값은 ''herdr --default-config''로 현재 binary에서 직접 생성하는 것이 가장 안전하다.
  * 잘못된 값은 safe default로 fallback되며 startup warning이 표시된다.

===== File Location =====
<code text>
Linux / macOS: ~/.config/herdr/config.toml
Windows:         %APPDATA%\herdr\config.toml
</code>

  * ''HERDR_CONFIG_PATH''는 기본 config file 경로를 override한다.
  * ''herdr --help''는 현재 실행 환경에서 resolve된 config 경로를 표시한다.
  * custom sound 같은 상대 경로는 config file directory를 기준으로 해석된다.

===== Authoring =====
==== Generate Defaults ====
<code bash>
# 검토용으로 전체 기본 설정 출력
herdr --default-config

# Linux / macOS 기본 경로에 저장
mkdir -p ~/.config/herdr
herdr --default-config > ~/.config/herdr/config.toml
</code>

<note important>
기존 config가 있으면 redirection으로 덮어쓰기 전에 backup한다. 현재 keybinding만 초기화하려면 전체 파일을 교체하지 말고 ''herdr config reset-keys''를 사용한다.
</note>

==== Minimal Example ====
<code toml>
onboarding = false

[terminal]
default_shell = "zsh"
shell_mode = "auto"
new_cwd = "follow"

[worktrees]
directory = "~/.herdr/worktrees"

[theme]
name = "catppuccin"

[ui.toast]
delivery = "herdr"
delay_seconds = 1
</code>

  * ''onboarding = false'': first-run setup을 다시 표시하지 않는다.
  * ''terminal.default_shell'': 새 interactive pane의 shell executable을 지정한다. command line이 아닌 executable 이름 또는 경로다.
  * ''terminal.shell_mode'': ''auto'', ''login'', ''non_login'' 중 shell startup mode를 선택한다.
  * ''terminal.new_cwd'': ''follow'', ''home'', ''current'' 또는 고정 경로를 사용한다. CLI의 명시적 ''--cwd''가 우선한다.
  * ''worktrees.directory'': Herdr가 만든 Git worktree checkout의 root directory다.

===== Keybindings =====
<code toml>
[keys]
prefix = "ctrl+b"
goto = "prefix+g"
new_tab = "prefix+c"
next_tab = "prefix+n"
previous_tab = "prefix+p"
focus_pane_left = "prefix+h"
split_horizontal = "prefix+minus"
</code>

  * 기본 keymap은 shell, editor, tmux 입력을 가로채지 않도록 prefix-first 방식이다.
  * key string은 ''ctrl+a'', ''alt+1'', ''prefix+n'', ''enter'', ''esc'', ''minus'' 같은 형식을 사용한다.
  * 일반 printable key를 prefix 없이 binding하면 평상시 typing을 가로챌 수 있다.
  * 하나의 action에 여러 shortcut이 필요하면 ''next_tab = ["prefix+n", "ctrl+alt+]"]''처럼 array를 사용한다.
  * active binding은 Herdr 안에서 ''prefix+?''로 확인한다.

==== Custom Command ====
<code toml>
[[keys.command]]
key = "prefix+alt+g"
type = "popup"
command = "lazygit"
description = "run lazygit"
width = "80%"
height = "80%"
</code>

  * ''type''은 ''popup'', ''pane'', ''shell'', ''plugin_action''을 사용할 수 있다.
  * Unix custom pane command는 ''/bin/sh -c'', detached command는 ''/bin/sh -lc''를 사용한다.
  * Windows command string은 ''cmd.exe /d /c''로 실행되므로 PowerShell syntax가 필요하면 ''powershell.exe''를 명시한다.

<note warning>
Custom command는 shell command를 실행한다. 출처가 불명확한 설정을 복사하지 말고 command와 인자를 검토한다.
</note>

===== Theme and UI =====
<code toml>
[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

[ui.sidebar.agents]
row_gap = 0
rows = [
  ["state_icon", "workspace", "tab"],
  ["agent"],
]
</code>

  * ''theme.name''은 built-in theme를 선택한다. host terminal ANSI palette를 따르려면 ''terminal''을 사용한다.
  * ''theme.auto_switch''는 terminal이 보고한 light/dark appearance에 따라 Herdr theme을 전환한다.
  * sidebar ''rows''는 표시할 token과 줄 구성을 정의한다. 지원 token과 제한은 공식 Config reference에서 확인한다.

===== Notifications =====
<code toml>
[ui.toast]
delivery = "herdr"
delay_seconds = 1

[ui.toast.herdr]
position = "bottom-right"

[ui.sound]
path = "sounds/notification.mp3"
</code>

  * ''delivery''는 ''herdr'', ''terminal'', ''system'', ''off''를 사용할 수 있다.
  * custom sound는 MP3 file을 사용하며 상대 경로는 config file directory 기준이다.
  * ''HERDR_DISABLE_SOUND''를 설정하면 sound notification을 비활성화한다.

===== Remote and Session =====
<code toml>
[remote]
manage_ssh_config = true

[session]
resume_agents_on_restore = true
</code>

  * ''remote.manage_ssh_config = true''이면 Herdr가 temporary private SSH config와 connection reuse socket을 관리한다. 사용자의 ''~/.ssh/config''와 system config가 먼저 포함된다.
  * ''session.resume_agents_on_restore''는 공식 integration이 유효한 native session reference를 제공한 pane에만 적용된다.

===== Precedence =====
  - ''HERDR_CONFIG_PATH''로 지정한 config file이 기본 platform 경로를 대체한다.
  - 선택된 config file의 TOML 설정을 읽는다.
  - CLI/socket API의 명시적 값이 해당 동작에서 config보다 우선한다. 예: ''workspace create --cwd PATH''.
  - invalid value는 safe default로 fallback되고 warning을 출력한다.

===== Validation =====
<code bash>
# 현재 binary가 제공하는 전체 기본값과 비교
herdr --default-config

# 실행 중인 server에 변경 적용
herdr server reload-config

# server와 client 상태 확인
herdr status

# keybinding section backup 후 초기화
herdr config reset-keys
</code>

  * reload는 대부분의 UI setting에 적용되지만 startup-only setting은 restart가 필요하다.
  * ''config reset-keys''는 ''config.toml''을 backup하고 ''[keys]''와 ''[[keys.command]]''를 제거한 뒤 built-in keymap을 사용한다.
  * log는 보통 ''~/.config/herdr/herdr.log'', ''herdr-client.log'', ''herdr-server.log''에서 확인한다.

===== Security =====
  * config file에 API token, password, private key를 직접 저장하지 않는다.
  * pane screen history나 log에는 terminal output과 민감한 command가 남을 수 있다. persistence 설정을 켜기 전에 저장 범위와 file permission을 확인한다.
  * ''HERDR_LOG''의 debug level은 운영 중 필요한 기간에만 사용하고 공유하기 전에 token, path, host 정보를 redact한다.
  * remote attach는 기존 SSH trust와 key policy를 따른다. host key 검증을 우회하지 않는다.

===== Troubleshooting =====
  * 변경이 반영되지 않으면 ''HERDR_CONFIG_PATH''와 ''herdr --help''의 resolve된 경로가 같은지 확인한다.
  * startup warning이 나오면 해당 key를 공식 Config reference와 ''herdr --default-config''에서 검색한다.
  * 새 pane의 shell이나 ''PATH''가 예상과 다르면 ''terminal.default_shell''과 ''terminal.shell_mode''를 점검하고 pane을 새로 만든다.
  * key 입력이 가로채지면 prefix 없는 printable binding을 제거하고 ''herdr config reset-keys''로 기본값을 복원한다.
  * remote attach가 불안정하면 먼저 일반 ''ssh TARGET''을 검증하고 필요할 때만 ''remote.manage_ssh_config = false''로 비교한다.

===== See Also =====
  * [[herdr:ko|Herdr CLI]]
  * [[https://herdr.dev/docs/configuration/|Herdr configuration]]
  * [[https://herdr.dev/docs/config-reference/|Herdr Config reference]]
  * [[https://herdr.dev/docs/keyboard/|Herdr keyboard guide]]

===== History =====
  * codex:: 2026-07-27 Added config location, TOML authoring, terminal, worktree, keybinding, theme, notification, remote, validation, and security guidance.

{{indexmenu>.#1|js}}