Command Line Interface

Volvicon supports command line arguments for controlling startup behavior from a terminal, shell script, or automation pipeline. Use volvicon-cli.exe as the command-line entry point; it forwards commands to the GUI executable with terminal-friendly behavior for informational flags.

Prerequisites:

• Volvicon installed and licensed (see License Guide)
• Familiarity with Windows Command Prompt or PowerShell
• For --py_script: Custom Scripting feature enabled (available on Professional and above licenses)

---

Launching Volvicon from the Command Line

Open a terminal, navigate to the Volvicon installation directory, and run the CLI launcher directly:

cd "C:\Program Files\Volvicon 2026.2.1"
volvicon-cli.exe [arguments]

You can also invoke Volvicon by full path from any working directory:

"C:\Program Files\Volvicon 2026.2.1\volvicon-cli.exe" [arguments]

Installation Directory

The installation directory name includes the version number, for example Volvicon 2026.2.1. Replace 2026.2.1 with your installed version. You can find the exact path in Help → About within the application.

Console Output

volvicon-cli.exe is a console executable designed for terminal use. For informational flags (--help, --version, --license_info) it waits and prints output in the current terminal. For workflow launches (project open/import/script), it starts the GUI process and returns immediately unless you pass --wait.

---

Viewing Available Arguments

Run volvicon-cli.exe with --cli_help to print launcher-specific usage summary:

volvicon-cli.exe --cli_help

Run volvicon-cli.exe with --help to print the same CLI usage summary (compatibility alias of --cli_help):

volvicon-cli.exe --help

The CLI prints the supported launcher and forwarded arguments with descriptions, then exits.

---

Command Line Arguments

Reference Table

Informational Commands

These flags are handled entirely by the CLI process. No GUI window is opened.

Argument	Description
--help, -h	Print full CLI usage summary and exit
--version, -v	Print version information and exit
--license_info	Print installed license details and exit
--status	Report whether the Volvicon GUI is currently running
--sysinfo	Print host system information (OS, CPU, GPU, RAM)

CLI Behavior Modifiers

These flags control how the CLI launcher itself operates.

Argument	Value	Description
--wait, -w	—	Wait for the launched GUI process and return its exit code
--timeout=<ms>	Milliseconds	Maximum time to wait before the CLI returns (0 = infinite, default)
--json	—	Print the operation result as JSON to standard output
--result_json=<path>	File path	Write the operation result as JSON to a file
--no-color	—	Disable colored console output (honors NO_COLOR env var)
--verbose	—	Print additional diagnostic messages during execution
--quiet, -q	—	Suppress all non-error output
--dry-run	—	Show the command that would be executed without launching the GUI

Volvicon Application Arguments (Forwarded to the GUI)

Any argument not recognized as a CLI flag is forwarded verbatim to the GUI executable.

Argument	Value	Description
--project_file=<path>	File path	Open a Volvicon project file (.vvcx) on startup
--volume_image_files=<paths>	;-separated paths	Import one or more volume image files or folders
--mask_image_files=<paths>	;-separated paths	Import one or more mask image files (requires loaded volumes)
--surface_files=<paths>	;-separated paths	Import one or more surface model files
--volume_mesh_files=<paths>	;-separated paths	Import one or more volume mesh files
--py_script=<path>	File path	Execute a Python script (.py) after the main window is shown
--clear_settings=yes	yes	Clear all saved application settings before loading the UI

Argument Format

Flags without values (--help, --version, --license_info) are passed as-is. Options with values use the --argument=value format. Paths that contain spaces must be enclosed in double quotes around the entire argument:

volvicon-cli.exe "--project_file=C:\My Data\scan.vvcx"

volvicon-cli.exe launcher options can be combined with forwarded Volvicon arguments, for example:

volvicon-cli.exe --wait --json --license_info

Paths Containing Spaces

If a path contains spaces, you must quote the entire --key=value argument. Quoting only the path value after = is not sufficient — the shell will split the unquoted portion at the first space and the argument will be malformed.

REM ✗ WRONG — shell splits on space; "1.nii.gz" becomes a separate token
volvicon-cli.exe --volume_image_files=C:\Samples\CT 1.nii.gz

REM ✓ CORRECT — entire argument is quoted
volvicon-cli.exe "--volume_image_files=C:\Samples\CT 1.nii.gz"

The same rule applies to semicolon-separated lists with spaces in any individual path:

REM ✓ CORRECT — entire argument (including both paths) is quoted
volvicon-cli.exe "--mask_image_files=C:\Samples\CT (threshold).nii.gz;C:\Samples\CT (threshold 2).nii.gz"

---

Opening a Project File

Use --project_file to open a .vvcx project file on startup:

volvicon-cli.exe --project_file=C:\Projects\patient_001.vvcx

Drag-and-Drop and Double-Click

If you double-click a .vvcx file in Windows Explorer, or drag it onto the Volvicon executable, Volvicon handles the project extension automatically without requiring the --project_file flag. You can also pass the path as a single bare argument:

volvicon-cli.exe "C:\Projects\patient_001.vvcx"

note

The bare single-argument shortcut only applies when the path ends with the .vvcx extension. For all other arguments, use the explicit --argument=value form.

---

Importing Volume Image Files

Use --volume_image_files to import one or more volume images at startup. Separate multiple paths or directories with a semicolon (;):

volvicon-cli.exe --volume_image_files=C:\Data\scan_001.nii

volvicon-cli.exe "--volume_image_files=C:\Data\scan_001.nii;C:\Data\scan_002.nii"

You can also pass a directory path, and Volvicon will discover the images within it:

volvicon-cli.exe --volume_image_files=C:\Data\DICOM_Series

Supported formats include DICOM, NIfTI, NRRD, MHD, and other formats supported by the Import dialog. Volvicon validates each path and prints a warning to the console for any file that does not exist or is not a supported format.

---

Importing Mask Image Files

Use --mask_image_files to import one or more mask image files. Separate multiple paths with a semicolon (;):

volvicon-cli.exe --mask_image_files=C:\Data\segmentation_mask.nii

volvicon-cli.exe "--mask_image_files=C:\Data\mask_a.nii;C:\Data\mask_b.nii.gz"

Supported formats include NIfTI (.nii, .nii.gz), MHA, MHD, and VTI.

Volume Dependency

Mask images can only be imported when at least one volume image is already loaded in the project. If no volumes are present, Volvicon prints a warning and skips the mask import. When combining --volume_image_files and --mask_image_files, volume images are imported first.

Bare-Path Detection

Mask image files share the same file formats as volume images (NIfTI, MHA, MHD, VTI). When passed as bare paths (without a --key=value flag), they are always detected as volume images. Use the explicit --mask_image_files= argument to import files as masks.

---

Importing Surface Model Files

Use --surface_files to import surface mesh files at startup:

volvicon-cli.exe "--surface_files=C:\Models\femur.stl;C:\Models\tibia.ply"

Unsupported file formats and non-existent paths produce console warnings; valid files proceed to import.

---

Importing Volume Mesh Files

Use --volume_mesh_files to import supported volume mesh files for simulation workflows:

volvicon-cli.exe --volume_mesh_files=C:\Meshes\bone_mesh.vtu

volvicon-cli.exe "--volume_mesh_files=C:\Meshes\mesh_a.vtu;C:\Meshes\mesh_b.vtk"

---

Executing a Python Script

Use --py_script to execute a Python script automatically after the main window is displayed. The script runs in the same Python environment as the interactive scripting editor, giving it full access to the Volvicon Scripting API.

volvicon-cli.exe --py_script=C:\Scripts\process_scan.py

License Requirement

Executing Python scripts via --py_script requires Custom Scripting (available on Professional and above licenses). If your license does not include this feature, Volvicon displays a warning and skips script execution.

Script Execution Timing

The script runs after the main window is fully shown. When combined with --project_file, the project load completes before the script fires. When combined with file import arguments (--volume_image_files, --mask_image_files, --surface_files, --volume_mesh_files), the import progress dialog runs first; the script fires after that dialog closes. In typical use the imported data is accessible from the script.

Medical Use Disclaimer

Command-line automation can accelerate processing, but it does not replace clinical review. In medical workflows, verify segmentation, measurements, and derived outputs in the interactive application before using results for diagnostic, treatment-planning, or regulatory decisions.

Script Requirements

• The file must exist and be readable at the path provided.
• The file must have a .py extension.
• The script runs asynchronously; startup is not blocked while the script executes.
• Output from the script (including print() statements) appears in both the in-application console and the terminal, if one is attached.

Security and Trust

Python scripts executed via --py_script run with full access to the Volvicon Scripting API and can perform any operation available in the interactive scripting environment, including file I/O, data manipulation, and UI interactions. Only execute scripts from trusted sources, as they can contain malicious code. In production environments, consider code review or digital signatures for automated scripts.

Example Scripts

The following workflow tutorials provide Python scripts suitable for use with --py_script:

Script	Description
Cone Beam Reconstruction and Void Analysis Workflow	Automates CT reconstruction, void analysis, and report generation from projection data
Wall-Thickness Analysis Workflow	Performs threshold segmentation, surface generation, and full 3D wall-thickness evaluation

Each tutorial page includes a downloadable .py file. Save the script locally and pass its path to --py_script:

volvicon-cli.exe --py_script=C:\Scripts\wall_thickness_analysis_workflow.py

---

Clearing Application Settings

Use --clear_settings=yes to reset all saved preferences, window layouts, and recent file history before the UI loads:

volvicon-cli.exe --clear_settings=yes

This is useful when troubleshooting configuration issues, or when deploying Volvicon on a new workstation where a previous user's settings should not carry forward.

warning

Clearing settings is irreversible. All saved preferences — including UI layout, display settings, and recently opened files — will be removed permanently.

---

Checking Application Status

Use --status to determine whether any Volvicon GUI instance is currently running:

volvicon-cli.exe --status

When one or more instances are running, the CLI reports the process count and lists each instance by PID and executable name. When no instance is detected, a brief message is printed.

Combine with --json for machine-readable output suitable for monitoring scripts:

volvicon-cli.exe --status --json

Example JSON output:

{
  "running": true,
  "gui_path": "C:\\Program Files\\Volvicon 2026.2.1\\Volvicon.exe",
  "instances": [
    { "pid": 14320, "exe": "Volvicon.exe" }
  ]
}

---

Displaying System Information

Use --sysinfo to print a summary of the host system configuration:

volvicon-cli.exe --sysinfo

The output includes:

Field	Description
OS	Operating system name and version
CPU	Processor model
GPU	Graphics adapter
Total RAM	Total physical RAM
Available RAM	Available physical RAM
Total Virtual Memory	Total virtual memory (physical + page file)
Available Virtual Memory	Available virtual memory
CPU Cores	Number of logical processor cores
Architecture	Target architecture (e.g., x86_64)
CLI Path	Absolute path to the volvicon-cli executable
GUI Path	Absolute path to the detected GUI executable

Combine with --json to produce a JSON object:

volvicon-cli.exe --sysinfo --json

Diagnostics

The --sysinfo output is useful when filing support tickets or comparing hardware configurations across workstations in a multi-seat deployment.

---

Displaying Version Information

Use --version to print the application name and version, then exit:

volvicon-cli.exe --version

No application window is shown. The version string is printed to the terminal and the process exits immediately. This option does not require a valid license.

For machine-readable version output:

volvicon-cli.exe --version --json

---

Displaying License Information

Use --license_info to print details about the installed license, then exit:

volvicon-cli.exe --license_info

The output includes:

Field	Description
License type	Edition tier (for example, Standard, Professional, Ultimate)
Serial number	License serial number, or n/a if not applicable
Valid from	Start date of the license
Expires	Expiration date of the license
Days remaining	Days until expiration (omitted for perpetual licenses)
Trial	Whether the license is a trial
Perpetual	Whether the license has no expiration

If no license file is installed, the output indicates that and provides a contact address for obtaining a license. If the license is invalid or has expired, the output reports that status.

note

--license_info requires the application settings to be initialized in order to locate the license file. A short startup sequence runs before output is produced; no application window is shown.

---

Combining Arguments

Multiple arguments can be combined in a single launch command. Arguments are processed independently and are not mutually exclusive, except where noted.

Open a Project and Run a Script

volvicon-cli.exe --project_file=C:\Projects\study.vvcx --py_script=C:\Scripts\analyze.py

The project file is opened first; the script executes after the main window is shown. In standard workflows, project loading completes before script execution begins.

Import Multiple Data Types

volvicon-cli.exe "--volume_image_files=C:\Data\ct_scan.nii" "--surface_files=C:\Models\implant.stl"

Import Volumes, Masks, and Surfaces Together

Load a CT volume, two threshold-derived masks, and a surface model in a single launch. Because the mask paths contain spaces, the entire --mask_image_files argument is quoted:

volvicon-cli.exe --volume_image_files="C:\Samples\CT.nii.gz" "--mask_image_files=C:\Samples\CT (threshold).nii.gz;C:\Samples\CT (threshold 2).nii.gz" --surface_files="C:\Samples\CT.stl"

Volume images are imported first, followed by masks (masks require at least one volume to be present), and then the surface model.

Import Files and Execute a Script

volvicon-cli.exe --volume_image_files=C:\Data\scan.nii --py_script=C:\Scripts\segment_and_export.py

The import dialog runs before the script fires; in the typical case the imported volume is accessible to the script through the Scripting API when it begins executing.

Reset Settings on Startup

volvicon-cli.exe --clear_settings=yes --project_file=C:\Projects\clean_start.vvcx

Argument Processing Order

When multiple data arguments are provided, Volvicon schedules them in the order they are registered: the project file opens first, then volume/mask/surface/mesh imports run after the main window is shown. The --py_script argument is always processed independently — it fires after data loading is initiated and, in the typical case, after data is available in the project.

---

Automating Workflows

Windows Batch Script

Create a .bat file to launch Volvicon with a fixed configuration:

@echo off
REM process_patient.bat
REM Launches Volvicon, loads a CT scan, and runs the segmentation script.

set VOLVICON="C:\Program Files\Volvicon 2026.2.1\volvicon-cli.exe"
set SCAN=C:\Data\Patients\Patient_042\ct.nii
set SCRIPT=C:\Scripts\segment_bone.py

%VOLVICON% --volume_image_files=%SCAN% --py_script=%SCRIPT%

PowerShell Script

# process_cohort.ps1
# Launches Volvicon once per patient folder found in the input directory.

$volvicon = "C:\Program Files\Volvicon 2026.2.1\volvicon-cli.exe"
$scriptPath = "C:\Scripts\auto_process.py"
$inputRoot  = "C:\Data\Cohort"

Get-ChildItem -Path $inputRoot -Filter "*.nii" -Recurse | ForEach-Object {
    $scan = $_.FullName
    Write-Host "Processing: $scan"
    & $volvicon "--volume_image_files=$scan" "--py_script=$scriptPath"
}

Per-File Processing in Scripts

When iterating over a dataset in a shell script, consider writing your Python script so that it reads a target file path from a project-level variable or from command line context. Alternatively, use --project_file to open a pre-configured project that references the correct data path, and let the Python script operate on whatever is already in the project.

Scheduled Task (Windows Task Scheduler)

To run a Volvicon workflow on a schedule:

1. Open Task Scheduler (taskschd.msc).
2. Click Create Basic Task and follow the wizard.
3. Set the trigger (e.g., daily at a specific time).
4. For the action, set:

• Program/script: "C:\Program Files\Volvicon 2026.2.1\volvicon-cli.exe"
• Add arguments: --project_file=C:\Projects\overnight.vvcx --py_script=C:\Scripts\overnight_report.py

5. Complete the wizard and verify the task runs correctly.

---

Secondary Instance Behavior

If Volvicon is already running and you launch it again, the running instance receives the arguments rather than a second window opening. Both --flag=value arguments and bare file path arguments are supported:

REM Open a project in the running Volvicon session:
volvicon-cli.exe --project_file=C:\Projects\study.vvcx

REM Import files into the running session:
volvicon-cli.exe "--volume_image_files=C:\Data\scan.nii;C:\Data\scan2.nii"

REM Execute a script in the running session:
volvicon-cli.exe --py_script=C:\Scripts\process_scan.py

REM Dispatch a bare file path (auto-detected by extension):
volvicon-cli.exe "C:\Projects\study.vvcx"

The following file types are recognized and dispatched to the existing session:

• .vvcx project files
• Volume image files (formats supported by the Import dialog)
• Mask image files (same formats as volume images — requires loaded volumes)
• Surface model files
• Volume mesh files
• .py Python scripts

The file or script is dispatched to the existing session and opened or executed immediately.

Secondary Instance Argument Handling

Informational flags (--help, --version, --license_info, --status, --sysinfo) and CLI-only modifiers (--json, --verbose, --wait, etc.) are handled by the CLI process itself and are not forwarded to the running instance. Only data-oriented arguments (--project_file, --volume_image_files, --mask_image_files, --surface_files, --volume_mesh_files, --py_script, --clear_settings) and bare file paths are dispatched.

note

This behavior requires that the singleton instance management is active. In environments where multiple independent Volvicon sessions are required, consult your system administrator.

---

Output Formatting

JSON Output

Append --json to any informational command to receive structured JSON output on standard output, suitable for parsing by scripts and automation tools:

volvicon-cli.exe --license_info --json
volvicon-cli.exe --status --json
volvicon-cli.exe --sysinfo --json
volvicon-cli.exe --version --json

For forwarded commands (--project_file, --py_script, etc.), --json prints a JSON result object summarizing the launch outcome. With --wait, the output includes the final child-process exit code.

To write the JSON result to a file instead of (or in addition to) standard output:

volvicon-cli.exe --wait --result_json=C:\Logs\result.json --project_file=C:\Data\scan.vvcx

Color Control

The CLI uses ANSI color codes to distinguish message severity (info, warning, error) in terminals that support them. To disable color output:

volvicon-cli.exe --no-color --license_info

The CLI also respects the NO_COLOR environment variable. When NO_COLOR is set to any value, color output is suppressed automatically without requiring the --no-color flag:

$env:NO_COLOR = "1"
volvicon-cli.exe --license_info

Verbosity

• --verbose enables diagnostic messages (registry lookups, resolved paths, timing) that are hidden by default.
• --quiet suppresses all output except error messages.
• When both are specified, --quiet takes precedence.

---

Exit Codes

The CLI returns numeric exit codes that can be tested in shell scripts and CI/CD pipelines:

Code	Name	Description
0	Success	Operation completed successfully
1	GeneralError	Unspecified error
2	ParseError	Command-line arguments could not be parsed
3	GuiNotFound	GUI executable was not found next to the CLI binary
4	LaunchError	The GUI process could not be started
5	IntegrityError	Binary integrity verification failed
6	IoError	File I/O error (e.g., writing --result_json output)
7	TimeoutError	--wait timed out before the child process exited
8	LicenseError	License file could not be read or is invalid

When --wait is active and the GUI exits normally, the CLI forwards the GUI's own exit code.

Checking Exit Codes in Scripts

PowerShell:

volvicon-cli.exe --license_info
if ($LASTEXITCODE -ne 0) {
    Write-Error "CLI returned exit code $LASTEXITCODE"
}

Command Prompt:

volvicon-cli.exe --license_info
if %ERRORLEVEL% NEQ 0 (
    echo CLI returned exit code %ERRORLEVEL%
)

---

Troubleshooting

The application launches but no data is loaded

• Verify the file path is correct and the file exists.
• Check that the path does not contain trailing spaces.
• Paths with spaces must be wrapped in quotes around the entire --key=value argument: "--project_file=C:\My Folder\scan.vvcx". Quoting only the path portion after = (for example --project_file="C:\My Folder\scan.vvcx") is not reliable across shells and may still be split incorrectly.
• Review terminal output for Warning: lines indicating invalid paths or unsupported formats. If you launch Volvicon.exe directly (instead of volvicon-cli.exe) in production builds, terminal output is generally not shown.

--py_script is ignored with no message

• Confirm your license includes the Custom Scripting feature (Professional and above).
• Ensure the file path is correct and the file has a .py extension.
• Check the application log for warnings (see Troubleshooting).

The script fails at runtime

• Run the script interactively through Advanced → Scripting to see the full error output.
• Verify that all paths referenced inside the script are absolute and use forward slashes or escaped backslashes.
• Ensure all required Python packages are available within the Volvicon scripting environment.

Console prompt does not return after closing Volvicon

This behavior can occur in non-production builds when running Volvicon from a terminal. It is not present in production (retail) releases, which behave as standard GUI applications and return the prompt immediately upon launch.

volvicon-cli.exe is not recognized

Ensure that the working directory is the Volvicon installation folder, or provide the full path to the executable. Adding the installation directory to the system PATH environment variable allows volvicon-cli to be invoked from any location.

Colored output appears garbled

Virtual terminal (VT100) escape sequences require Windows 10 version 1607 or later. On older systems, or when output is redirected to a file, pass --no-color to suppress ANSI codes.

---

Related Topics

• Python Scripting Fundamentals — Introduction to the Volvicon Scripting API
• Batch Processing and Automation — Scripting patterns for processing multiple datasets
• Scripting API Code Examples — Ready-to-use scripts for common workflows
• License Guide — Confirming your license tier and enabled modules