Configuration¶

Config directory¶

Termapy looks for configs in the first directory that matches:

The OS default location is %APPDATA%\termapy on Windows, ~/Library/Application Support/termapy on macOS, and ~/.config/termapy on Linux (respects XDG_CONFIG_HOME).

Creating a new config¶

When you create a new config (first run, or Cfg → New), termapy shows a quick-setup dialog where you pick a name, a serial port, and a baud rate. Hit Connect to save and connect, or Advanced to drop into the full JSON editor for fine-grained control.

JSON config file¶

Each configuration is stored as a JSON file at <config_dir>/<name>/<name>.cfg. On first run, termapy creates a default config for you. You can edit it from within the app by clicking the center title bar button or using /cfg.

Here is an example config for a device called iot_device:

{
    "config_version": 29,
    "title": "IoT Device",
    "border_color": "blue",
    "max_lines": 10000,
    "default_ui": "tui",
    "vt100_hint": true,
    "cmd_prefix": "/",
    "cli_prompt": "$(CFG)> ",
    "cli_completion": true,
    "config_read_only": false,
    "profile_path": "",
    "validate_typed_args": false,
    "serial": {
        "port": "COM4",
        "baud_rate": 115200,
        "custom_baud": false,
        "byte_size": 8,
        "parity": "N",
        "stop_bits": 1,
        "flow_control": "none"
    },
    "encoding": "utf-8",
    "cmd_delay_ms": 0,
    "protocol": "text",
    "ndjson_field_routing": {
        "response_id": "id",
        "error_field": "error",
        "event_field": "event"
    },
    "default_response_timeout_ms": 1000,
    "auto_connect": true,
    "auto_reconnect": true,
    "on_connect_cmd": "status\nhelp",
    "tui_on_connect_cmd": "",
    "cli_on_connect_cmd": "",
    "mcp_on_connect_cmd": "",
    "eol": "\r",
    "eol_rx": "auto",
    "send_bare_enter": false,
    "echo": false,
    "echo_fmt": "[purple]$(CFG)> {cmd}[/]",
    "log_file": "",
    "show_traceback": false,
    "proto_frame_gap_ms": 50,
    "proto_results_template": "{name}_results.json",
    "timestamps": false,
    "eol_markers": false,
    "line_no": false,
    "hex": false,
    "request_mode": false,
    "request_err_pattern": "(?i)^(ERROR|ERR|FAULT)\\b",
    "strip_device_echo": false,
    "max_grep_lines": 100,
    "file_xfer_root": "",
    "cfg_enabled": true,
    "run_enabled": true,
    "proto_enabled": true,
    "record_enabled": true,
    "custom_buttons": [
        {
            "enabled": true,
            "name": "Reset",
            "command": "ATZ",
            "tooltip": "Reset device"
        },
        {
            "enabled": true,
            "name": "Init",
            "command": "ATZ\\nAT+BAUD=115200",
            "tooltip": "Reset and set baud"
        }
    ]
}

This file would be saved at termapy_cfg/iot_device/iot_device.cfg.

Config field reference¶

Connection behavior¶

auto_connect and auto_reconnect are independent settings. auto_connect opens the port when a config loads (app startup or config switch). auto_reconnect retries the connection when the port drops or a manual connect attempt fails -- it does not control startup behavior. While reconnecting, the title bar turns amber and shows a spinner.

Config management¶

Click the Cfg button in the title bar, click the config name, or use the command palette to open the config picker. Configs are listed newest first with size, last-updated age, port, baud, and title.

The picker's actions:

• Load: switch to the highlighted config. If the configured port is not available, a port picker is shown.
• Edit: open the highlighted config in the JSON editor
• New: create a new config from defaults. If one serial port is detected it is used automatically; if multiple ports are found a picker is shown before opening the editor.
• Rename: rename the highlighted config. The termapy_cfg/<name>/ folder and the <name>.cfg inside it move together (with the command history); renaming the active config reloads it.
• Delete: delete the highlighted config file (asks for confirmation)
• Cancel: close the picker

The JSON editor provides:

• Save: write changes to the current config file
• Save As: save as a new config (creates a new subfolder)
• Cancel: discard changes

Invalid JSON is caught before saving, with the error shown inline.