NetX I/O 4 CLI

The NetX I/O application comes in two different forms:

  1. Desktop app (Mac OS and Windows)
  2. CLI tool (Linux, Mac OS, Windows)

The CLI (command-line interface) tool runs "headless" (no user interface) and allows you to programmatically drive NetX I/O. It can be wrapped in shell scripts and scheduled via cron (or other task managers) and allows you to set up various sync points on a workgroup file server. The CLI tool is packaged as a jar file and executed with Java.

This article outlines the steps needed to start running the NetX I/O command-line tool, with Watched Folder mode as an example.


Windows users: NetX I/O requires the Microsoft Visual C++ Redistributable to be installed before it can run. For instructions on how to obtain this package, see

Step 1: Make sure JDK is installed locally

Type "java -version" on the command line to check the Java version:

$ java -version
java version "1.8.0_20"
Java(TM) SE Runtime Environment (build 1.8.0_20-b26)
Java HotSpot(TM) 64-Bit Server VM (build 25.20-b23, mixed mode)

If the version printed is anything other than "1.8.x", you will need to download a supported version of Java from Oracle:

Step 2: Download the NetX I/O jar file

You can download the netxio.jar file from our Service Portal, found in the I/O section of the Product Downloads page. 

Step 3: Create a local app storage folder on your computer

Create a folder on your workstation for NetX I/O to write application files, including logs, clientId data file, and lostandfound folder. Example:

Mac OS




Step 4: Move the .jar file to your app folder

Copy the netxio.jar file into your app folder created in step 3. Example:

Mac OS




Step 5: Choose the source folder on your computer

The storage location you created in Step 3 is for managing NetX I/O's application files. Now you need to choose (or create) a folder that will be the root of all the sub-folders and files you want to upload to NetX. This folder can live anywhere on your local filesystem, but do NOT nest the source folder inside of your application folder. Example:

Mac OS




Step 6: Create an I/O user in NetX

NetX I/O logs into NetX using supplied credentials for a pre-existing user, and actions will be performed on behalf of that user.  It's best to create a separate account for your NetX I/O user. If you were to log in to NetX and then log out as the same user logged in via NetX I/O, it disrupts the processes in I/O. For Watched Folder mode, a Manager-level user (or higher) is required. If you're running NetX I/O in Sync mode, you must configure it to run with an Administrator-level user. You will need to know the username and password for the NetX I/O user.

Step 7: Choose your target folder in NetX

This is the folder in NetX to which sub-folders and files from your local source folder will be written. Make sure that the user account you are running NetX I/O with has appropriate permissions to write to this target folder.



Step 8: Parameters for the command line

Parameter Details


This parameter sets the minimum memory for NetX IO. 512MB of RAM is usually sufficient. This parameter MUST come before

Example: 512M


This parameter sets the maximum memory for NetX IO. 2048MB of RAM is usually sufficient. This parameter MUST come before

Example: 2048M


This parameter sets the Java classpath and must point to the NetX library directory. This parameter MUST come before

Example: /Users/me/NetxIO/netxio-4.1.0.jar


This is the URL of your NetX server instance.


Note: if you are using an https address, see -useInsecureSSL below.


This is the username of your NetX user.


This is the password of your NetX user.


This is the folder (or "category") in NetX which files and folders will sync.

Example: /Projects/Campaigns/2022


This is the local directory where folders and files are synced with the NetX server.

Example: /Users/me/Desktop/SourceFiles


This sets NetX I/O into the operational mode of your choice. *Merge and Sync modes are experimental and are not supported for use in mission-critical environments. Use at your own risk.

Value options:







Local storage for NetX I/O program files, including logs, clientId data file, and lostandfound folder. Please see the storage capacity note below.

Example: /Users/me/NetxIO


This sets NetX I/O to run the sync process every 15 minutes.

Example: 15


Optional. No value is required. If you are connecting with HTTPS and can't register your SSL certificate with NetX IO, this will disable any certificate verification.


Optional. For watchedFolder, import, and export modes, specifying 'blind' means the analysis step will be skipped. When
enabled, imports are much faster if you're not concerned with avoiding duplicates. This option also allows for versioning of files on the NetX server (watchedFolder and import modes only).


Optional. If illegal characters are encountered in either files or folders, then use this replacement character (single).

_ (underscore)
- (dash)

Start NetX I/O CLI

Step 1: Using the command line

Type the following using the parameters defined above. Example:

Mac OS

java -Xms512M -Xmx2048M -cp "/Users/me/NetxIO/netxio-4.1.0.jar" -url -username netxio_user -password 123456789 -netxSourceFolder "/Projects/Campaigns/2022" -localSourceDir "/Users/me/Desktop/SourceFiles" -mode watchedFolder -replacementCharacter _ -localStorageDir "/Users/me/NetxIO_workfiles" -useInsecureSSL -loop 15


java -Xms512M -Xmx2048M -cp "C:\Users\me\NetxIO\netxio-4.1.0.jar" -url -username netxio_user -password 123456789 -netxSourceFolder "/Projects/Campaigns/2022" -localSourceDir "C:\Users\me\Desktop\SourceFiles" -mode watchedFolder -replacementCharacter _ -localStorageDir "C:\Users\me\NetxIO" -useInsecureSSL -loop 15


  • Ensure the -cp directive is placed before the class or it will be interpreted as a parameter to the class, instead of interpreted by Java.
  • NetX I/O could potentially use a large amount of RAM, especially in sync mode. In the above example, the Java heap is set to start with 512MB (-Xms512M) and can utilize up to 2048MB (-Xmx2048M), but you should adjust this in accordance with your setup.
  • Be aware of the capacity of the underlying storage when configuring the localStorageDir setting. If imports encounter significant errors, failed import files will be copied to the "lost and found" directory under this path. If that storage facility runs out of space, critical errors will occur.
  • If you start NetX I/O using the command line, you may want to background the process, because closing the command window will quit NetX I/O. Additionally, you can add the NetX I/O commands to your workstation startup items.  
  • If the user account running NetX I/O does not have appropriate access permissions to the NetX folders it is trying to sync, this error will be present in the logs:
    [NetX I/O] ERROR (com.netxposure.external.client.rpc.ApiException: JSON-RPC Error 4003: Object not found (invalid category_id (18)) (null))

Step 2: Start moving folders and files

Drop folders or files into your local watched folder. Wait for the loop time, and then see the folders and files replicated on the other side. Rinse and repeat!

Step 3: Use a config file instead of command-line arguments

You can also set all your NetX I/O options within a configuration file. In this scenario, you only set the configuration file (the "-config" option) in the command line:

java -Xms512M -Xmx2048M -cp "/Users/me/NetxIO/netxio-4.1.0.jar" -config "/Users/me/NetxIO/"

Here's what an example configuration file might look like:


Option names are separated from their corresponding values with an equals sign (=). Do not wrap config values with quotes (like you might do on the command line). Command-line parameters that require no arguments — like blind in the example above — can be set with a value of true.

Built-in help

You can obtain details on all the NetX I/O configurations and advanced troubleshooting tools by running the CLI tool with the -help flag.

java -cp /Users/me/NetxIO/netxio-4.1.0.jar -help

Merge and Sync modes are experimental and are not supported for use in mission-critical environments. Use at your own risk.

Running multiple NetX I/O processes on a single workstation

If you want to run multiple instances of NetX I/O on a single workstation, you need to ensure that each instance uses its own local app storage and sync folders. Do not attempt to run multiple instances of NetX I/O CLI with a shared local app storage directory!

Was this article helpful?
0 out of 0 found this helpful