Skip to content

Remote Control Overview

This section introduces the remote-control command-line workflow for hfVisualizer and hfSectionVisualizer.

This document is written for users who want to control hfVisualizer or hfSectionVisualizer from the command line.

Use remote-control commands when you want to:

  • control an already running viewer instance
  • automate repetitive GUI actions
  • save repeatable command sequences as scripts
  • avoid opening interactive dialogs during batch work

1.1 Quick Start

If you only need the fastest path:

  1. start the application normally
  2. run list or status
  3. open a file or connect to the active document
  4. run display, selection, preprocessing, or postprocessing commands as needed
  5. save or export results

1.1.1 Launch the application normally

hfVisualizer.exe [file]
hfSectionVisualizer.exe [file]

1.1.2 Send a command to a running instance

hfVisualizer --remote [--target <id>] [--timeout-ms <ms>] <command> [args]
hfSectionVisualizer --remote [--target <id>] [--timeout-ms <ms>] <command> [args]
  • In remote-control commands, <id> means one target-instance identifier from list.
  • The recommended form is the full uuid shown in the first column of list.
  • A unique uuid prefix or the full server name also works, but the full uuid is the clearest and safest choice when multiple instances are running.

1.1.3 Typical first commands

hfVisualizer --remote list
hfVisualizer --remote target set 60bae260-bf0a-4ad1-86ae-e9ef22bc8133
hfVisualizer --remote status
hfVisualizer --remote open D:\Work\model.inp
hfVisualizer --remote save

1.2 Common Workflow Rules

1.2.1 Choosing the target window

  • Use hfVisualizer --remote target set <id> when you want repeated hfVisualizer --remote ... commands to keep using the same running instance.
  • Use hfSectionVisualizer --remote target set <id> when you want repeated hfSectionVisualizer --remote ... commands to keep using the same running instance.
  • Use hfVisualizer --remote target show to inspect the saved default target, or hfVisualizer --remote target clear to remove it.
  • Use hfSectionVisualizer --remote target show to inspect the saved default target, or hfSectionVisualizer --remote target clear to remove it.
  • Use --target <id> when you want to override the saved default target for one command, or when you do not want to save a default target.
  • <id> is one target-instance identifier from list.
  • The recommended <id> is the full uuid shown in the first column of list.
  • A unique uuid prefix or the full server name from list also works.
  • When more than one instance is running, prefer the full uuid or a long enough unique prefix instead of a very short prefix.
  • For hfVisualizer, if --target is omitted and a saved default target exists, that saved target is used first.
  • For hfSectionVisualizer, if --target is omitted and a saved default target exists, that saved target is used first.
  • If no saved default target exists and exactly one instance is running, that instance is used automatically.
  • If multiple instances are running and neither --target nor a saved default target is available, the command fails so that it does not affect the wrong window.
  • If the saved default target no longer exists, the command fails and asks you to run target clear or target set again instead of guessing another window.
  • target set/show/clear are local client commands for both apps. They do not send remote-control requests to the GUI process.
hfVisualizer --remote target set <id>
hfVisualizer --remote target show
hfVisualizer --remote target clear
hfSectionVisualizer --remote target set <id>
hfSectionVisualizer --remote target show
hfSectionVisualizer --remote target clear
  • target set <id>:
  • resolves one live app instance from the full uuid, a unique uuid prefix, or the full server name shown by list
  • stores that instance as the local default target used when --target is omitted later
  • target show:
  • prints JSON showing whether a default target is saved
  • reports resolved: true when the saved target still matches a live instance
  • reports resolved: false with an error when the saved target is stale
  • target clear:
  • removes the saved default target
  • Target resolution order for normal hfVisualizer --remote ... commands:
  • explicit --target <id>
  • saved default target from target set
  • automatic single-instance selection when exactly one instance is running
  • otherwise fail instead of guessing
  • --target <id> remains available as a one-command override even after target set.

Examples:

hfVisualizer --remote list
hfVisualizer --remote target set 60bae260-bf0a-4ad1-86ae-e9ef22bc8133
hfVisualizer --remote target show
hfVisualizer --remote status
hfVisualizer --remote --target 864937a3-0922-4a0c-b377-9a2ec5c10d82 status
hfVisualizer --remote target clear

hfSectionVisualizer --remote list
hfSectionVisualizer --remote target set 4d2f7aa1-5f6d-4e23-9c62-6a63dc7f914b
hfSectionVisualizer --remote target show
hfSectionVisualizer --remote status
hfSectionVisualizer --remote --target 7f3f8f20-8a68-4d3c-bd8d-3e6c6d7f0b12 status
hfSectionVisualizer --remote target clear

1.2.2 File path behavior

  • Absolute paths are used as-is.
  • Relative paths are resolved from the top-level CLI working directory.
  • If a command needs a save path but the current document has never been saved, it fails with SAVE_PATH_REQUIRED.
  • The remote CLI receives arguments after PowerShell or cmd.exe has already split the command line into tokens.
  • Double quotes are not part of the final value. They only keep one shell argument together.
  • If one argument contains no spaces, quoted and unquoted forms are normally equivalent. This applies to select node, select element, select surface, select edge, and other commands in the same way.
  • Use double quotes when one argument itself contains spaces, such as --content "..." or a file path with spaces. Quotes may also be kept for readability even when they are not strictly required.

1.2.3 Non-interactive behavior

  • Remote-control commands are designed for automation and must not open modal dialogs.
  • If user input would normally be required in the GUI, the remote-control command fails instead of prompting.

1.2.4 Working with scripts

<app> --remote [--target <id>] [--timeout-ms <ms>] script <file>
<app> --remote [--target <id>] script-save [file]
  • A script file contains one command tail per line.
  • Do not include <app> --remote in the script file.
  • Do not include --target <id> in the script file. Target selection is resolved by the outer script command.
  • For hfVisualizer and hfSectionVisualizer, target set/show/clear are local client commands and are not valid inside a script file.
  • Blank lines and # comment lines are ignored.
  • Nested script inside a script file is not allowed.
  • script is fail-fast: it stops on the first failed line.

1.2.5 Session and history files

  • Runtime files are stored under <sessionRoot>/.hyfeast/.
  • Default history/script files:
  • hfVisualizer: <sessionRoot>/.hyfeast/hfVisualizer.<uuid>.ipc.txt
  • hfVisualizer local default target: <sessionRoot>/.hyfeast/hfVisualizer.defaultTarget.json
  • hfSectionVisualizer: <sessionRoot>/.hyfeast/hfSectionVisualizer.<uuid>.ipc.txt
  • hfSectionVisualizer local default target: <sessionRoot>/.hyfeast/hfSectionVisualizer.defaultTarget.json
  • script-save writes command tails in the same format accepted by script.

1.2.6 Exit codes

  • hfVisualizer and hfSectionVisualizer use the same remote CLI exit-code values.
  • Success: 0
  • Invalid arguments or usage: 2
  • Target selection failure: 3
  • Remote-control connection failure: 4

  • Remote-control timeout: 5

  • When a command fails, the CLI normally prints an error line such as ERROR[...] and also returns a non-zero exit code.

  • For example, if hfVisualizer --remote new fails with SAVE_PATH_REQUIRED, the console shows the error text and the exit code is still 2.

Check the exit code in cmd.exe:

hfVisualizer --remote new
echo %ERRORLEVEL%

Check the exit code in PowerShell:

hfVisualizer --remote new
$LASTEXITCODE

The same pattern applies to hfSectionVisualizer:

hfSectionVisualizer --remote status
echo %ERRORLEVEL%