Skip to main content

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.

ArgumentDescription
--help, -hPrint full CLI usage summary and exit
--version, -vPrint version information and exit
--license_infoPrint installed license details and exit
--statusReport whether the Volvicon GUI is currently running
--sysinfoPrint host system information (OS, CPU, GPU, RAM)

CLI Behavior Modifiers​

These flags control how the CLI launcher itself operates.

ArgumentValueDescription
--wait, -w—Wait for the launched GUI process and return its exit code
--timeout=<ms>MillisecondsMaximum time to wait before the CLI returns (0 = infinite, default)
--json—Print the operation result as JSON to standard output
--result_json=<path>File pathWrite 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.

ArgumentValueDescription
--project_file=<path>File pathOpen a Volvicon project file (.vvcx) on startup
--volume_image_files=<paths>;-separated pathsImport one or more volume image files or folders
--mask_image_files=<paths>;-separated pathsImport one or more mask image files (requires loaded volumes)
--surface_files=<paths>;-separated pathsImport one or more surface model files
--volume_mesh_files=<paths>;-separated pathsImport one or more volume mesh files
--py_script=<path>File pathExecute a Python script (.py) after application startup
--exit_after_script=yesyes or noClose Volvicon as soon as the --py_script script finishes (default no)
--headlessyes or noRun without a user interface. Requires --py_script and always closes when the script finishes
--headless_delay=<ms>MillisecondsTime a headless run waits for startup to settle before the script begins (default 1000)
--clear_settings=yesyesClear 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.

Label Images Only

A mask file has to hold a label image: one value per voxel, whole numbers from 0 to 65535, with 0 as background. A grayscale 3D image such as a CT scan in Hounsfield units contains negative values and a wider range, so it is rejected and a warning is printed. Import it with --volume_image_files instead. See Masks for details.

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"

Supported surface formats: STL (.stl), PLY (.ply), OBJ (.obj), VRML 2.0 (.wrl, .vrml), glTF (.gltf, .glb), AMF (.amf), STEP (.step, .stp), IGES (.iges, .igs), VTP (.vtp), and points (.xyz).

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

Point Files

An .xyz file imports as a point cloud with no faces. Use Poisson Remesh to reconstruct a triangle mesh from it before measuring surface area or exporting to a mesh format.

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"

Supported volume mesh formats: VTK unstructured grids (.vtu, .vtk), Abaqus/CalculiX (.inp), Nastran (.bdf, .nas), LS-DYNA (.k, .dyn, .key), ANSYS (.cdb), Gmsh and Fluent (.msh), and OpenFOAM (.foam).

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.

Message Boxes During Unattended Runs​

An operation that reports a result, or asks for a confirmation, opens a message box and waits for a button to be clicked. On an unmonitored machine the script stops there until somebody attends to it. Call set_message_box_suppression() at the start of the script to keep it moving:

import ScriptingApi as api

app = api.Application()

# Skip the boxes that only have to be acknowledged. Confirmations are still asked.
app.set_message_box_suppression(api.MsgBoxSuppression.Notifications)

# Skip every message box. Each confirmation is answered with its default button.
app.set_message_box_suppression(api.MsgBoxSuppression.All)

# Restore the normal behavior.
app.set_message_box_suppression(api.MsgBoxSuppression.Off)

Every skipped message box is printed on the script console, the same place print() output goes, and written to the application log. Warnings and errors are marked as error output:

[Message] Information: The operation finished.
[Warning] Import: The file could not be read.
[Error] Export: Access to the target folder was denied.
Confirmations are answered for you

MsgBoxSuppression.All answers each confirmation with its default button, and that default is not the same for every confirmation. Object delete confirmations default to Yes, so the deletion goes through without anybody being asked, while several others default to No and are therefore declined. show_question_message_box() returns True. Use MsgBoxSuppression.Notifications when the script should still stop for confirmations.

The setting applies to the running script only and returns to Off when the script finishes, so a script cannot leave the application silent for the next interactive user. While the script runs, however, the setting is application-wide: a message box that the application opens for any other reason is skipped as well and reported the same way, so avoid working in the interface during a suppressed run.

Dialogs that are not message boxes are unaffected. License dialogs, file selection dialogs, and progress dialogs still open and still wait for input, so a script that reaches one of them stops there regardless of the suppression mode.

Example Scripts​

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

ScriptDescription
Cone Beam Reconstruction and Void Analysis WorkflowAutomates CT reconstruction, void analysis, and report generation from projection data
Wall-Thickness Analysis WorkflowPerforms 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

Closing Volvicon When the Script Finishes​

By default Volvicon stays open after a --py_script script has run, so you can inspect the result. Add --exit_after_script=yes to close the application as soon as the script finishes, which is what a batch job or a scheduled task needs:

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

The flag accepts yes or no (true/1 and false/0 are also accepted). Any other value is treated as no, and the reason is written to the application log.

Volvicon closes whether the script succeeded or failed, and reports the outcome through its exit code. Add --wait so the CLI blocks until the run is over and returns that code to your shell; without --wait the CLI returns as soon as Volvicon has been started and you cannot test the result. See Exit Codes.

Suppress Message Boxes in the Script

An unattended run cannot answer a message box. Volvicon reports its own script failures in the application log and through the exit code instead of in a dialog, but a message box opened by an operation inside the script still waits for a click and keeps the process alive. Call set_message_box_suppression() at the start of the script, as described in Message Boxes During Unattended Runs. Use --timeout=<ms> together with --wait as a safety net: when the timeout expires, the CLI stops the run and returns exit code 7.

Requires --py_script

--exit_after_script only controls what happens after a script run. Used without --py_script, it prints a warning and Volvicon stays open.

Install the License First

The Unattended Script Exit Codes describe a run that reached the script. If no valid license is installed on the machine, Volvicon opens the license dialog during startup and waits there instead, so the script never starts and no script exit code is produced. Confirm the license with volvicon-cli.exe --license_info before scheduling an unattended run, and pass --timeout=<ms> with --wait so a run that stops at a dialog is cut short instead of waiting forever.

A --headless run does not open that dialog. It reports the problem on the console and ends with exit code 24, so an unlicensed machine is reported rather than left waiting. See Running Without a User Interface.

Nothing Is Saved on the Way Out

Volvicon shuts down without asking to save. Data imported with --volume_image_files or produced by the script exists only in memory unless the script writes it out, so the script has to save every project, mask, surface, measurement, or report it is meant to produce.

Ignored When Volvicon Is Already Running

If a Volvicon session is already open, the script is forwarded to that session and --exit_after_script is ignored: a session that belongs to the user in front of the screen, and that may hold unsaved work, is never closed by a second launch. The CLI prints a warning when this happens. Check with volvicon-cli.exe --status before an automated run.

Add --headless to run the script in a session of its own instead. A headless run starts beside the open session, leaves it untouched, and closes itself when the script finishes. See Running Without a User Interface.

Running Without a User Interface​

Use --headless to run Volvicon with no window at all. This is the mode to use on a server, in a scheduled task, or in a build pipeline, and it is also the mode to use when you want to keep working in Volvicon while a batch job runs beside you.

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

A headless run behaves like an ordinary run in every way that matters to a script: the same project, the same import and export formats, the same Scripting API, the same preferences, and the same application log. What changes is everything that needs somebody at the screen.

BehaviorNormal runHeadless run
Main window and splash screenShownNever shown
Message boxes and dialogsWait for a clickAnswered automatically and reported on the console and in the log
ClosingStays open unless --exit_after_script=yes is passedAlways closes when the script finishes
A Volvicon session already runningArguments are handed to that sessionA separate session is started, and the open session is left alone
License unavailable or invalidatedThe license dialog opensReported on the console; the run ends with exit code 24
Waiting for the resultNeeds --waitAlways waited for, so the exit code reaches your shell

--headless requires --py_script: a run with no window has no other way to be given work. Without it the run reports the problem and ends with exit code 21.

Anything the script prints appears in the terminal while it runs, together with the text of any message box that was answered for it. The same output is written to the application log, which is what an unattended run with no terminal leaves behind.

Combining With Other Arguments​

--headless combines with every data argument. Files are loaded first and the script runs after them:

volvicon-cli.exe --headless --volume_image_files=C:\Data\scan.nii --py_script=C:\Scripts\segment.py
volvicon-cli.exe --headless --project_file=C:\Projects\study.vvcx --py_script=C:\Scripts\report.py

Startup Delay​

The main window is initialized off-screen so rendering and other standard startup work are ready without appearing on the desktop. Volvicon then gives startup one second to settle before the script begins. Use --headless_delay to change that, in milliseconds, up to 600000:

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

Raise it if a script fails early on a slow or heavily loaded machine; lower it to shorten the runtime of a job that starts many short runs in a row.

What a Headless Run Leaves Alone

A headless run shares its settings and working directory with the interactive session, so it deliberately leaves the state that belongs to that session untouched: the window layout, the recent file list, the autosave project file, and the interactive undo history are neither written nor removed by it. If the headless run needs disk-backed undo data, it keeps that data separate and removes only its own. Preferences are read as usual, so a script sees the same configuration the interactive session uses.

Message Boxes Are Answered For You

A headless run answers every message box with its default button and prints the title and the text on the console, in the same way set_message_box_suppression(api.MsgBoxSuppression.All) does. Read Message Boxes During Unattended Runs before writing a script that relies on a confirmation: some confirmations default to Yes and some to No.

Nothing Is Saved Automatically

As with any unattended run, the script has to write out every project, mask, surface, measurement, or report it is meant to produce. Nothing is saved on the way out.

Bound a Run That Might Not Finish

A headless run is waited for with no time limit, so a script that loops forever keeps the caller waiting too. Add --timeout=<ms> to stop the run and return exit code 7 once that time has passed:

volvicon-cli.exe --headless --py_script=C:\Scripts\process_scan.py --timeout=1800000
Running the GUI Executable Directly

volvicon-cli.exe is the entry point to use. Volvicon.exe --headless works as well, but Volvicon is a windowed application: a shell returns to its prompt right after starting it, so a batch file cannot read its exit code. Use volvicon-cli.exe, which waits for the run and reports its result.

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:

FieldDescription
OSOperating system name and version
CPUProcessor model
GPUGraphics adapter
Total RAMTotal physical RAM
Available RAMAvailable physical RAM
Total Virtual MemoryTotal virtual memory (physical + page file)
Available Virtual MemoryAvailable virtual memory
CPU CoresNumber of logical processor cores
ArchitectureTarget architecture (e.g., x86_64)
CLI PathAbsolute path to the volvicon-cli executable
GUI PathAbsolute 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:

FieldDescription
License typeEdition tier (for example, Standard, Professional, Ultimate)
Serial numberLicense serial number, or n/a if not applicable
Valid fromStart date of the license
ExpiresExpiration date of the license
Days remainingDays until expiration (omitted for perpetual licenses)
TrialWhether the license is a trial
PerpetualWhether 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 application startup. 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.

Run a Script and Close Volvicon​

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

The volume is imported, the script runs, Volvicon closes itself, and the CLI returns the result of the script. This is the form to use in batch files, scheduled tasks, and CI pipelines. See Closing Volvicon When the Script Finishes.

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 application startup. 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% --exit_after_script=yes --wait
if %ERRORLEVEL% NEQ 0 (
    echo Processing failed with exit code %ERRORLEVEL%
    exit /b %ERRORLEVEL%
)

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"

    # One Volvicon session per scan: it closes itself when the script is done,
    # and --wait blocks until then so the next scan starts on a free machine.
    & $volvicon "--volume_image_files=$scan" "--py_script=$scriptPath" --exit_after_script=yes --wait
    if ($LASTEXITCODE -ne 0) {
        Write-Warning "$scan failed with exit code $LASTEXITCODE"
    }
}
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: --headless --project_file=C:\Projects\overnight.vvcx --py_script=C:\Scripts\overnight_report.py
  1. Complete the wizard and verify the task runs correctly.

--headless keeps a scheduled task from putting a window on the screen of whoever is signed in, closes the run when the report has been produced, and lets Task Scheduler record its result. Without it, use --exit_after_script=yes --wait to get the same closing behavior with a window.

Run the Task as the Account That Holds the License

The installed license is recorded per Windows user account. A task that runs as SYSTEM, or as a service account that has never opened Volvicon, does not find it: the run reports that a license is required and ends with exit code 24. Configure the task to run as the account that installed the license, and confirm it from that account with volvicon-cli.exe --license_info.

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:

Behavior modifiers such as --wait, --timeout, --json, and --verbose are not drawn: the CLI consumes them on every path and never forwards them, so they do not change which branch a command takes. --headless requires --py_script.

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.

--exit_after_script is dispatched but deliberately ignored by the running instance, which keeps a session that may hold unsaved work from being closed by a second launch.

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:

CodeNameDescription
0SuccessOperation completed successfully
1GeneralErrorUnspecified error
2ParseErrorCommand-line arguments could not be parsed
3GuiNotFoundGUI executable was not found next to the CLI binary
4LaunchErrorThe GUI process could not be started
5IntegrityErrorBinary integrity verification failed
6IoErrorFile I/O error (e.g., writing --result_json output)
7TimeoutError--wait timed out before the child process exited
8LicenseErrorLicense 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.

Unattended Script Exit Codes​

An unattended run reports the result of the script through the exit code of the Volvicon process. Every --headless run is unattended, and so is a --py_script run that carries --exit_after_script=yes. A headless run is always waited for; for the others, add --wait so the CLI forwards that code to your shell:

CodeDescription
0The script ran to completion without reporting an error
20The script raised an error while executing
21The script file is missing, unreadable, empty, or not a .py file
22Custom Scripting is not included in the installed license
23The Python environment could not be initialized
24A usable license is unavailable or cannot be validated (headless runs only)

These values start at 20 so they never overlap with the CLI codes listed above. With --json or --result_json=<path>, the same value is reported as the child_exit_code field of the result object.

The license check comes before any of this, and it is the difference between a scheduled task that fails and one that hangs:

Confirm the license with volvicon-cli.exe --license_info from the account the task will run as, and pass --timeout=<ms> with --wait so a normal run that stops at the dialog is cut short instead of waiting forever.

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 the Warning: lines that volvicon-cli.exe prints for invalid paths or unsupported formats. Warnings raised inside Volvicon itself are written to the application log.

--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.
  • Confirm the argument carries a value. --py_script on its own, or --py_script= with nothing after the =, provides no path; the reason is written to the application log, and an unattended run ends with exit code 21.
  • Check the application log for warnings (see Troubleshooting).

Volvicon stays open after the script finished​

  • Use --headless, which always closes the run when the script finishes and never opens a window in the first place.
  • Confirm that --exit_after_script=yes was passed and that the value is yes (an unrecognized value is treated as no and the reason is written to the application log).
  • --exit_after_script requires --py_script; on its own it does nothing.
  • Check whether a Volvicon session was already running when the command was issued. In that case the script is forwarded to the open session, which is never closed. Run volvicon-cli.exe --status to verify.
  • If the script opens a message box, the run waits for it to be closed. Call set_message_box_suppression() at the start of the script and pass --timeout=<ms> with --wait so the run cannot block indefinitely.

The script fails at runtime​

  • Run the script interactively through Advanced → Scripting to see the full error output.
  • With --exit_after_script=yes the error is written to the application log instead of shown in a dialog, and the process exit code identifies the failure (see Unattended Script Exit Codes).
  • 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.