From 65b86ae716f1d927c7d2a96fb44f330841bb5af2 Mon Sep 17 00:00:00 2001 From: cotta-dev Date: Thu, 2 Apr 2026 23:41:16 +0900 Subject: [PATCH 1/2] feat: improve -C config help to match docs/config-reference.yaml detail --- configs/config-help.txt | 192 ++++++++++++++++++++++------------------ 1 file changed, 107 insertions(+), 85 deletions(-) diff --git a/configs/config-help.txt b/configs/config-help.txt index 5356ca9..0d7cb04 100644 --- a/configs/config-help.txt +++ b/configs/config-help.txt @@ -1,90 +1,112 @@ ================================================================================ -Retri Configuration File (config.yaml) Reference +Retri Configuration File Reference ================================================================================ -This file is written in YAML format. The variables allowed in each section are -strictly defined. - --------------------------------------------------------------------------------- -Variable Precedence & Aggregation Rules --------------------------------------------------------------------------------- - -1. Single Variable Priority (<) - Evaluation Order: defaults < groups < device_types < hosts < env vars < CLI - (Values on the right override values on the left.) - - Environment variables: - - RETRI_SSH_PASSWORD: Overrides password from config (but not CLI -p) - - RETRI_SSH_SECRET: Overrides secret from config (but not CLI -s) - -2. Command Aggregation (+) - Execution Order: defaults + groups + device_types + hosts - (Commands are concatenated in this order and all are executed.) - --------------------------------------------------------------------------------- -Section Definitions & Available Variables --------------------------------------------------------------------------------- - -[defaults] Section - Sets global default values for the application. - - Available Variables: - user, password, secret : SSH/Sudo credentials (default fallback). - command, commands, command_file - : Commands to execute. - log_dir : Directory path for saving logs. - suffix : Suffix string appended to log filenames. - device_type : Default device type (e.g., "linux"). - parallel : Parallel execution count or "auto". - timestamp : Enable/disable timestamp in logs (true/false). [defaults only] - filename_format : Format string for log filenames. [defaults only] - timestamp_format : Date format string for filenames. [defaults only] - -[device_types] Section - Defines settings specific to device types. Keys are arbitrary identifiers - (e.g., "cisco_ios", "linux"). - - Special Behavior for 'linux': - If device_type is set to "linux", commands are executed via direct SSH execution - (non-interactive, no PTY) to ensure clean output without terminal control codes. - All other types default to interactive PTY sessions. - - Available Variables: - setup_commands : Commands executed immediately after login. [device_types only] - prompt_regex : Regex to detect command prompts. [device_types only] - exit_command : Command to exit the session (default: "exit"). - Use "quit" for Huawei devices. [device_types only] - user, password, secret : Credentials common to this device type. - command, commands, command_file - : Commands common to this device type. - log_dir : Log storage directory for this type. - -[groups] Section - Groups multiple hosts together for shared configuration. - - Available Variables: - name : Group name (Required). - hosts : List of hostnames belonging to the group. - (e.g., ["host1", "host2"]) - user, password, secret : Credentials common to the group. - command, commands, command_file - : Commands common to the group. - log_dir : Log storage directory for the group. - suffix : Suffix for log files in this group. - device_type : Device type applied to this group. - -[hosts] Section - Configures settings for individual hosts. - - Available Variables: - host : Hostname or IP (Required). - Supports range expansion (e.g., "switch-[01-10]"). - groups : List of group names this host belongs to. - (e.g., ["group1"]) - user, password, secret : Host-specific credentials. - command, commands, command_file - : Host-specific commands. - log_dir : Host-specific log directory. - device_type : Host-specific device type. +Priority chain (low → high): + defaults < device_types < groups < hosts < env vars < CLI flags +Commands are AGGREGATED across all layers (not overridden). +suffix / filename_format / timestamp_format are only read from defaults (+ CLI). + +${VAR} in any string value is expanded from environment variables at runtime. + +Environment variable overrides (between config and CLI): + RETRI_SSH_PASSWORD — overrides password if not set in config + RETRI_SSH_SECRET — overrides secret if not set in config + +Legend: + [required] must be specified + [optional] can be omitted; default shown + +================================================================================ +defaults — global fallback applied to all hosts +================================================================================ + +defaults: + user: "" # [optional] default: OS user — passed to ssh as-is + password: "" # [optional] default: none — SSH password. Prefer ${VAR} or key auth + secret: "" # [optional] default: none — sudo / enable secret. Prefer ${VAR} + command: "" # [optional] default: none — single command (ignored if commands set) + commands: [] # [optional] default: [] + command_file: "" # [optional] default: none — path to file with commands (one per line) + log_dir: "~/retri-logs" # [optional] default: ~/retri-logs + prompt_timeout: 300 # [optional] default: 300 — seconds to wait for prompt (interactive only) + + # defaults-only fields: + device_type: "linux" # [optional] default: linux — fallback device type for all hosts + parallel: "auto" # [optional] default: 5 — concurrent executions. "auto"=num CPUs or integer + timestamp: true # [optional] default: true — prefix each log line with a timestamp + filename_format: "{host}_{timestamp}{suffix}.log" + # [optional] vars: {host} {timestamp} {suffix} + timestamp_format: "YYYYMMDD_HHmmss" + # [optional] symbols: YYYY MM DD HH mm ss + suffix: "" # [optional] default: none — appended to {suffix} in filename_format + +================================================================================ +device_types — reusable profiles for interactive (PTY) devices + applied after defaults, before groups / hosts +================================================================================ + +device_types: + my_device: # key name — referenced via device_type in defaults / groups / hosts + user: "" # [optional] + password: "" # [optional] + secret: "" # [optional] + command: "" # [optional] + commands: [] # [optional] + command_file: "" # [optional] + log_dir: "" # [optional] default: inherit from defaults + prompt_timeout: 0 # [optional] default: inherit from defaults (0 = inherit) + + # device_types-only fields: + prompt_regex: "[#>] ?$" # [optional] default: [#>] ?$ — regex to detect CLI prompt + setup_commands: [] # [optional] default: [] — sent once at session start + exit_command: "exit" # [optional] default: exit — use "quit" for Huawei + + # Note: device_type "linux" uses direct SSH exec (no PTY) for clean output. + # All other types use interactive PTY sessions. + +================================================================================ +groups — apply shared settings to multiple hosts + applied after defaults and device_types +================================================================================ + +groups: + - name: "my_group" # [required] — referenced via groups: [...] in hosts, or -g CLI flag + user: "" # [optional] + password: "" # [optional] + secret: "" # [optional] + command: "" # [optional] + commands: [] # [optional] + command_file: "" # [optional] + log_dir: "" # [optional] default: inherit from defaults + prompt_timeout: 0 # [optional] default: inherit (0 = inherit) + + # groups-only fields: + device_type: "" # [optional] — override device_type for hosts in this group + suffix: "" # [optional] — overrides defaults.suffix for this group's logs + hosts: [] # [optional] — hostnames / ranges (e.g. "sw-[01-03]") + +================================================================================ +hosts — individual host definitions (highest config priority) +================================================================================ + +hosts: + - host: "myhost" # [required] — hostname, IP, or SSH config alias + # Range syntax: "sw-[01-03]" expands to sw-01, sw-02, sw-03 + user: "" # [optional] + password: "" # [optional] + secret: "" # [optional] + command: "" # [optional] + commands: [] # [optional] + command_file: "" # [optional] + log_dir: "" # [optional] default: inherit from defaults + prompt_timeout: 0 # [optional] default: inherit (0 = inherit) + + # hosts-only fields: + device_type: "" # [optional] — override device_type for this host + groups: [] # [optional] — group names this host belongs to + +================================================================================ +Full reference with examples: docs/config-reference.yaml ================================================================================ From a5bcc2c9977fc3e8c4ce3e721289310bce5e8f1a Mon Sep 17 00:00:00 2001 From: cotta-dev Date: Thu, 2 Apr 2026 23:47:49 +0900 Subject: [PATCH 2/2] feat: embed docs/config-reference.yaml directly for retri -C MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removes configs/config-help.txt — docs/config-reference.yaml now serves as the single source of truth for both GitHub browsing and retri -C output. Co-Authored-By: Claude Sonnet 4.6 --- configs/config-help.txt | 112 ---------------------------------------- main.go | 2 +- 2 files changed, 1 insertion(+), 113 deletions(-) delete mode 100644 configs/config-help.txt diff --git a/configs/config-help.txt b/configs/config-help.txt deleted file mode 100644 index 0d7cb04..0000000 --- a/configs/config-help.txt +++ /dev/null @@ -1,112 +0,0 @@ -================================================================================ -Retri Configuration File Reference -================================================================================ - -Priority chain (low → high): - defaults < device_types < groups < hosts < env vars < CLI flags - -Commands are AGGREGATED across all layers (not overridden). -suffix / filename_format / timestamp_format are only read from defaults (+ CLI). - -${VAR} in any string value is expanded from environment variables at runtime. - -Environment variable overrides (between config and CLI): - RETRI_SSH_PASSWORD — overrides password if not set in config - RETRI_SSH_SECRET — overrides secret if not set in config - -Legend: - [required] must be specified - [optional] can be omitted; default shown - -================================================================================ -defaults — global fallback applied to all hosts -================================================================================ - -defaults: - user: "" # [optional] default: OS user — passed to ssh as-is - password: "" # [optional] default: none — SSH password. Prefer ${VAR} or key auth - secret: "" # [optional] default: none — sudo / enable secret. Prefer ${VAR} - command: "" # [optional] default: none — single command (ignored if commands set) - commands: [] # [optional] default: [] - command_file: "" # [optional] default: none — path to file with commands (one per line) - log_dir: "~/retri-logs" # [optional] default: ~/retri-logs - prompt_timeout: 300 # [optional] default: 300 — seconds to wait for prompt (interactive only) - - # defaults-only fields: - device_type: "linux" # [optional] default: linux — fallback device type for all hosts - parallel: "auto" # [optional] default: 5 — concurrent executions. "auto"=num CPUs or integer - timestamp: true # [optional] default: true — prefix each log line with a timestamp - filename_format: "{host}_{timestamp}{suffix}.log" - # [optional] vars: {host} {timestamp} {suffix} - timestamp_format: "YYYYMMDD_HHmmss" - # [optional] symbols: YYYY MM DD HH mm ss - suffix: "" # [optional] default: none — appended to {suffix} in filename_format - -================================================================================ -device_types — reusable profiles for interactive (PTY) devices - applied after defaults, before groups / hosts -================================================================================ - -device_types: - my_device: # key name — referenced via device_type in defaults / groups / hosts - user: "" # [optional] - password: "" # [optional] - secret: "" # [optional] - command: "" # [optional] - commands: [] # [optional] - command_file: "" # [optional] - log_dir: "" # [optional] default: inherit from defaults - prompt_timeout: 0 # [optional] default: inherit from defaults (0 = inherit) - - # device_types-only fields: - prompt_regex: "[#>] ?$" # [optional] default: [#>] ?$ — regex to detect CLI prompt - setup_commands: [] # [optional] default: [] — sent once at session start - exit_command: "exit" # [optional] default: exit — use "quit" for Huawei - - # Note: device_type "linux" uses direct SSH exec (no PTY) for clean output. - # All other types use interactive PTY sessions. - -================================================================================ -groups — apply shared settings to multiple hosts - applied after defaults and device_types -================================================================================ - -groups: - - name: "my_group" # [required] — referenced via groups: [...] in hosts, or -g CLI flag - user: "" # [optional] - password: "" # [optional] - secret: "" # [optional] - command: "" # [optional] - commands: [] # [optional] - command_file: "" # [optional] - log_dir: "" # [optional] default: inherit from defaults - prompt_timeout: 0 # [optional] default: inherit (0 = inherit) - - # groups-only fields: - device_type: "" # [optional] — override device_type for hosts in this group - suffix: "" # [optional] — overrides defaults.suffix for this group's logs - hosts: [] # [optional] — hostnames / ranges (e.g. "sw-[01-03]") - -================================================================================ -hosts — individual host definitions (highest config priority) -================================================================================ - -hosts: - - host: "myhost" # [required] — hostname, IP, or SSH config alias - # Range syntax: "sw-[01-03]" expands to sw-01, sw-02, sw-03 - user: "" # [optional] - password: "" # [optional] - secret: "" # [optional] - command: "" # [optional] - commands: [] # [optional] - command_file: "" # [optional] - log_dir: "" # [optional] default: inherit from defaults - prompt_timeout: 0 # [optional] default: inherit (0 = inherit) - - # hosts-only fields: - device_type: "" # [optional] — override device_type for this host - groups: [] # [optional] — group names this host belongs to - -================================================================================ -Full reference with examples: docs/config-reference.yaml -================================================================================ diff --git a/main.go b/main.go index cb8cc93..f98d5bf 100644 --- a/main.go +++ b/main.go @@ -10,7 +10,7 @@ import ( //go:embed configs/config.yaml var defaultConfigContent []byte -//go:embed configs/config-help.txt +//go:embed docs/config-reference.yaml var helpContent string // Version is set via ldflags by GoReleaser (e.g., -X main.Version=1.2.3).