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.

The keys are kept in one order, grouped by what they set: identity, port, connecting, line text, display, device replies, device profile, files, protocol tests, startup and frontends, buttons. termapy writes every config that way, the editor's Save included, so a key you add anywhere moves to its group.

Here is an example config for a device called iot_device:

{
    "config_version": 33,
    "title": "IoT Device",
    "border_color": "blue",
    "serial": {
        "port": "COM4",
        "baud_rate": 115200,
        "custom_baud": false,
        "byte_size": 8,
        "parity": "N",
        "stop_bits": 1,
        "flow_control": "none"
    },
    "auto_connect": true,
    "auto_reconnect": true,
    "on_connect_cmd": "/run startup",
    "tui_on_connect_cmd": "",
    "cli_on_connect_cmd": "",
    "mcp_on_connect_cmd": "",
    "encoding": "utf-8",
    "eol": "\r",
    "eol_rx": "auto",
    "eol_markers": false,
    "send_bare_enter": false,
    "cmd_delay_ms": 0,
    "multiline_paste": true,
    "multiline_paste_delay_ms": 10,
    "echo": false,
    "echo_fmt": "[purple]$(CFG)> {cmd}[/]",
    "timestamps": false,
    "line_no": false,
    "hex": false,
    "max_lines": 10000,
    "max_grep_lines": 100,
    "protocol": "text",
    "ndjson_field_routing": {
        "response_id": "id",
        "error_field": "error",
        "event_field": "event"
    },
    "request_mode": false,
    "request_err_pattern": "(?i)^(ERROR|ERR|FAULT)\\b",
    "strip_device_echo": false,
    "json_style": "compact",
    "profile_path": "",
    "validate_typed_args": false,
    "default_response_timeout_ms": 1000,
    "log_file": "",
    "file_xfer_root": "",
    "proto_frame_gap_ms": 50,
    "proto_results_template": "{name}_results.json",
    "default_ui": "tui",
    "quiet_start": true,
    "vt100_hint": true,
    "cmd_prefix": "/",
    "cli_prompt": "$(CFG)> ",
    "cli_completion": true,
    "show_traceback": false,
    "cfg_enabled": true,
    "run_enabled": true,
    "proto_enabled": true,
    "record_enabled": true,
    "config_read_only": false,
    "custom_buttons_side": "bottom",
    "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.

A $(env.NAME) template may sit on a boolean key too, as in "echo": "$(env.ECHO|false)": the expanded text is read with the boolean vocabulary (on/off/true/false/yes/no/1/0/y/n/t/f), a value outside it refuses the load naming the key, and a variable that does not resolve and has no fallback falls back to the default with a warning. A bare JSON string in a boolean key is never read as a token; it is reported as a type warning.

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.

On-connect commands¶

on_connect_cmd runs after every connect, then the frontend's own tui_, cli_ or mcp_on_connect_cmd. Each field holds one command, run as if typed. For several, put them in a .run file and set the field to /run <name>, as the demo does with /run welcome.

Before config version 30 a field could hold several commands separated by \n. Loading such a config moves them into a script named for the field, run/mcp_on_connect.run for mcp_on_connect_cmd, sets the field to /run mcp_on_connect, and says so in a config warning. A script of that name with other content is never overwritten; the new one gets _2, _3, and so on.

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. A name that already exists asks before its .cfg is replaced; the rest of its folder is kept. /cfg.new <name> <port> does the same from the command line.
• 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. /cfg.rename <name> <new> renames any other config.
• Delete: delete the highlighted config and its whole folder -- run scripts, profile, logs and captures -- after asking. It is /cfg.delete <name>, so it refuses the active config (load another first), and a config another program holds open is refused with nothing removed.
• 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.