Command line

Introduction

Qinertia features a powerful Command Line Interface (CLI) to easily integrate Qinertia GNSS/INS post processing with third party software. Power users can also use Qinertia CLI to automate processing tasks, batch process logs and optimize their overall processing workflow.

Qinertia CLI is a pure command line application with no GUI at all. It runs quietly and never asks the user to interact with it. It has been designed for computer to computer interaction but can also be easily used by human beings.

Qinertia CLI is available on Windows, Linux and Mac OS X platforms and is a standard feature for all Qinertia licenses. However, a specific OEM integrator license and agreement is required if you would like to resell or package Qinertia in your software. Please contact your sales representative for more information.

CLI Concepts

Qinertia CLI relies heavily on JSON files to describe jobs to do but also to get status and feedback. JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is both human and computer friendly. You can find more information at https://www.json.org/

To use Qinertia CLI you have to prepare a processing job using a JSON file and then launch this job using the dedicated Qinertia CLI application. All the steps are then executed automatically such as importing data, downloading base stations, processing the mission and exporting the results. During this process, Qinertia CLI returns progress and status information using JSON lines format through the pipe.

Finally, when Qinertia CLI has done the processing, several processing reports in JSON or PDF format can bee generated to provide an extensive feedback on how the processing went.

Qinertia CLI application

The Qinertia CLI application is shipped with standard Qinertia installation package so power users can write complex scripts to automate processing with Qinertia. On Windows, if you have used the default installation path, you should find the binary at:

C:\Program Files\SBG Systems\Qinertia\bin\qinertia-cli.exe

CLI options

You can display a full help that lists all available options by simply typing:

qinertia-cli.exe --help-all

You should get the following output:

Qinertia. SBG Systems post-processing software.
Usage: qinertia-cli [OPTIONS] SUBCOMMAND

Options:
  -h,--help                             Print this help message and exit
  --help-all                            Expand all help
  -v,--version                          Display program version information and exit

Subcommands:
process
  Process a project using settings defined in the specified json process file.
  Options:
    -u,--user <username> (Env:QINERTIA_CLI_PROCESS_USER)
                                          Username
    -p,--password <password> (Env:QINERTIA_CLI_PROCESS_PASSWORD)
                                          Password
    --license <license> (Env:QINERTIA_CLI_PROCESS_LICENSE)
                                          License key or path to an offline license file
    --status-output <name> (Env:QINERTIA_CLI_PROCESS_STATUS_OUTPUT)
                                          A pipe name, stdout or stderr
    --process-file <file> REQUIRED (Env:QINERTIA_CLI_PROCESS_PROCESS_FILE)
                                          Path to a command line process file
    --output <directory> (Env:QINERTIA_CLI_PROCESS_OUTPUT)
                                          Path to a directory where exports should be stored
    --input <directory> (Env:QINERTIA_CLI_PROCESS_INPUT)
                                          Path to a directory where input files should be taken from
    --resources <directory> (Env:QINERTIA_CLI_PROCESS_RESOURCES)
                                          Path to a directory where resource files (export profile, ...) should be taken from
    --project <directory> (Env:QINERTIA_CLI_PROCESS_PROJECT)
                                          Path to a directory where project should be saved
    --logs <file> (Env:QINERTIA_CLI_PROCESS_LOGS)
                                          Write session logs into <file>
    --overwrite-output                    Overwrite existing outputs

login
  Authenticates with user/pass, caching the auth token.
  Options:
    -u,--user <username> REQUIRED         Username
    -p,--password <password>              Password

logout
  Logout any connected user. Clear cached auth tokens.

user-info
  Returns information on the user currently logged in.
  Options:
    --status-output <name> (Env:QINERTIA_CLI_LOG_INFO_STATUS_OUTPUT)
                                          A pipe name, stdout or stderr

update
  Handle Qinertia updates.
  Options:
    --check REQUIRED                      Check if update is available.

host-id
  Prints licensing host id.

roam
  Get an offline Qinertia license.
  Options:
    -u,--user <username>                  Username. If not provided, current logged account will be used.
    -p,--password <password>              Password. If not provided, you will be asked to type it.
    --license <license> REQUIRED          License key.
    -o,--output <file>                    Output license file. If not specified, license will be installed globally.
    --duration <duration>                 Roaming duration in days.

revoke
  Revoke a checked out offline Qinertia license.
  Options:
    -u,--user <username>                  Username. If not provided, current logged account will be used.
    -p,--password <password>              Password. If not provided, you will be asked to type it.
    --license <license>                   License file. If not provided, the global Qinertia checked out license will be revoked.

last-revoke-key
  Get the last used license revoke key.

Environment Variables

Qinertia CLI defines and use several environment variables to ease integrating in production and server environments. The environment variables are used to define the arguments passed to the qinertia-cli binary.

Each CLI argument that can be defined using environment variable is describe in the CLI built-in help as shown above.

For example, you can use the environment variable QINERTIA_CLI_PROCESS_OUTPUT to define the directory where all exported data has to be stored.

Exit Codes

The Qinertia CLI application only implement two exit codes. The exit code should be checked by the calling application or script to easily know if a processing could be completed or have failed. Please find below a short description for each exit code.

Exit Code	Description
0	Success Qinertia was able to process the log and execute configured export and report jobs with no fatal error. You still have to check status returned by Qinertia as well as the processing report to to validate data quality and overall processing workflow.
1	Warning Qinertia was able to process the log and generate a JSON session report but some error might have occured (A missing export profile or a missing report template for example). You will find more information about the issue in the JSON lines.
2	Fatal The processing has failed at some point. More details have been reported over the console and/or in the log files. No processing report has been generated.
3	Licensing Error A licensing error occurred. For example, the requested license might be unavailable or might not give you access to the requested feature.

OEM Packaging

The Qinertia CLI application is available for Windows, Linux and Mac OS X platforms. You can easily ship Qinertia CLI with your application to integrate a professional GNSS/INS post processing solution within an automated and complex workflow.

You can either rely on the Qinertia installer using the quiet mode or manually copy the Qinertia directory into your own installation package.

Please feel free to contact SBG Systems support@sbg-systems.com team.

OEM Licensing

The standard Qinertia license lets end users access Qinertia CLI to create automated processing scripts. However, OEM integrators need a specific Qinertia license to be authorized to resell and package Qinertia CLI. Please contact SBG Systems sales@sbg-systems.com team for more information.

Software Updates

Qinertia CLI offers a dedicated update command to check if a new update is available. If a new update is available, a download link is provided to the new setup package for your operating system.

It is then, the user's responsibility to download and execute the setup package and install the new version manually.

qinertia-cli update --check
New version is available: 3.3.4356-stable.
=== Qinertia 3.3 Update ===
Release notes: https://support.sbg-systems.com/sc/qd/latest/download-release-notes/qinertia-3-3-4356-stable
Download link: https://update.sbg-systems.com/data/3f153db9-c1db-49cb-952d-ec7d7d9e42b1/Qinertia_v3.3.4356-stable.exe

License & Authentication

Before you can process a log, Qinertia has to make sure you have a valid license. Qinertia CLI supports both online floating license and offline node locked licenses.

User Information

You can easily check if Qinertia already has a valid installed license by using the user-info command. Once a valid license is check out or install, Qinertia keeps it unless you issue a logout or your revoke the license.

You can output the results as human readable information or to JSON lines with the additional option --status-output to ease machine to machine integration.

Please find below an example when Qinertia is successfully logged with a valid floating license:

qinertia-cli user-info
User Profile:
        Name : Jean Dupont
        Email: jdupont@gmail.com
License:
        Key     : AFZXHDDG3I
        Name    : Qinertia Pro
        Type    : Perpetual
        Validity: 16/07/2023

If no user is already logged in and thus no valid license is setup, this command should return the following:

qinertia-cli user-info
[Error] - No user logged in.

Floating License

This is the easiest way to use Qinertia CLI, you have to provide your credentials username and password and optionally the license id to use. Qinertia automatically contacts SBG Systems license server to check in/out a license.

User credentials are required to connect to SBG Systems license server and two modes of operation are offered by Qinertia.

You can either provide in each command line call your credentials and optionally the license id to use as shown in the example below:

qinertia-cli process --user jdupont@gmail.com --password tintin --license XFG5D8Z46A --process-file demoUav.json

Or you can enter your credentials only once and let Qinertia cache the authentication information. Qinertia doesn't need credential information in subsequent calls until you explicitly logout:

qinertia-cli login --user jdupont@gmail.com --password tintin

You can logout at any moment by typing the following command:

qinertia-cli logout

Node Locked

Qinertia CLI can be used offline and also supports node locked licenses. A node locked license is bound to the computer on which Qinertia is running. Qinertia can thus be used without having to check over internet for license validity.

There are two ways to get and install a node locked license:

Use Qinertia CLI roam command to let Qinertia automatically check, fetch and install the offline license. This method is only applicable if an internet access is available during initial license installation.
Get the computer host-id using Qinertia CLI and then visit the SBG Systems license management website to generate and download a license file for the computer host id. This method works even if the destination computer has no internet access at all.

Please read the How to use Qinertia offline page to learn how to generate an offline license file and revoke it when you don't need it anymore.

Using Internet

Qinertia can automatically fetch and install locally the license with the roam command. Qinertia requires an internet connection for this step and you have to provide user credentials as well as the license key to fetch.

Install the license

If the command is execute successfully, one seat is consumed and the license is installed locally. You can define a roaming duration after which the license is automatically invalided from the local computer and the seat is given back.

qinertia-cli.exe roam --user jdupont@gmail.com--password tintin --license LAXFDR4W3N --duration max

Use the license

The license has been installed locally on the computer. You can thus use Qinertia directly without having to provide credentials nor license information. No internet connection is required to use Qinertia. You can, for example start a processing using the command below:

qinertia-cli process --process-file demoUav.json

Revoke the license

At any time, you can revoke the license and give the seat back to the license server. As for the the license installation process, Qinertia requires an internet connection for this step:

qinertia-cli revoke

Offline Mode

If Qinertia is running on a computer that couldn't access internet, please follow this procedure to generate and install the license.

Generate the license

To generate an offline license file, you need the computer host id on which Qinertia CLI is running. You can easily query the computer host id using the following command:

qinertia-cli host-id

You should get a code such as 01ab392d239567 that identifies your computer hardware. The host id is required to generate the offline license file on the https://license.sbg-systems.com management platform.

Use the license

Once you have a valid offline license file, you can use it with Qinertia CLI. Simply provide the license file path each time you call Qinertia CLI. This is done using the --license option as shown in the example below:

qinertia-cli process --license C:\\MyApplication\myQinertiaLicense.lic --process-file demoUav.json

Revoke the license

If you don't need the offline license anymore and would like to give back the seat, you can also use Qinertia CLI to revoke the license. There are two ways to revoke an offline license depending on if Qinertia CLI can access internet:

If Qinertia CLI can access internet, simply use the revoke command. You can optionally provide user login information and explicitly define which license file has to be revoked.
If Qinertia CLI has no internet access, you should first get a revoke key using the command last-revoke-key and then use the returned key in https://license.sbg-systems.com to release the license.

Revoke Key

Keep the revoke key carefully until you have successfully returned the license on the online license management platform. If you lost the revoke key, you will not be able to release the seat consumed by the offline license.

Processing a mission

Qinertia CLI needs a JSON processing file that describes the whole processing job. Please read the Process file documentation to learn how to write this file.

Options

The command process is used to execute a processing job. This command offers several options to ease the integration as describe below:

Option	Optional	Description
--user		Qinertia user name credentials used to check for license validity. See license and authentication
--password		Qinertia user password credentials used to check for license validity. See license and authentication
--license		Optionally specify a license id to use, this is only relevant if you have more than one valid Qinertia license. See license and authentication
--process-file		Path to the JSON Process file that describe the job to execute.
--resources		Define the base path to use for all resources files such as export profiles or report templates. This base path is used when you provide relative files in the processing JSON.
--input		Define the base path to use for all input files that use a relative path. The input files are data you import for example.
--output		Define the base path to use for all output files that use a relative path. This option will affect exported data as well as published processing reports.
--status-output		Enable JSON lines status output information over either the `stdout` or `stderr` pipe. The calling process can monitor in real time Qinertia CLI progress and status. Please see Status output for more details.
--project		You can provide a path where Qinertia CLI can create and store a standard Qinertia project. This project can then be opened using Qinertia GUI to review the data and for troubleshooting. If this option is not provided, Qinertia CLI do the processing and only store exported data and reports. All temporary data is deleted and no Qinertia GUI project is created.
--logs		You can provide a file to store Qinertia CLI application logs.
--overwrite-output		If specified, Qinertia CLI is allowed to overwrite any existing file with no warning or request. If not specified, Qinertia CLI will never overwrite an existing file and rather stop the processing.

Example

The following command line process a log and monitor the progress using JSON line output on stdout. All the input files, using a relative path in the JSON Process file, are read from /home/qinertia/data folder. All output files such as exported data and generated PDF processing reports are stored in /home/qinertia/results folder. The Qinertia CLI application log files are stored in the /var/log/qinertia directory. Finally, no user credentials are provided as the application has been already granted using the login command.

./qinertia-cli process --license GH3XFV4MPO --process-file /home/qinertia/job/jobProcess.json --input /home/qinertia/data --output /home/qinertia/results --status-output stdout --logs /var/logs/qinertia

If everything went well, you should get the following output:

{"category":"licensing","type":"info","payload":{"message":"Fetching available licenses ..."}}
{"category":"licensing","type":"info","payload":{"message":"Fetching license GH3XFV4MPO ..."}}
{"category":"creation","type":"import","payload":{"progress":0}}
{"category":"creation","type":"import","payload":{"progress":14}}
{"category":"creation","type":"import","payload":{"progress":22}}
{"category":"creation","type":"import","payload":{"progress":29}}
{"category":"creation","type":"import","payload":{"progress":40}}
{"category":"creation","type":"import","payload":{"progress":50}}
{"category":"creation","type":"import","payload":{"progress":61}}
{"category":"creation","type":"import","payload":{"progress":71}}
{"category":"creation","type":"import","payload":{"progress":78}}
{"category":"creation","type":"import","payload":{"progress":87}}
{"category":"creation","type":"import","payload":{"progress":90}}
{"category":"creation","type":"import","payload":{"progress":90}}
{"category":"creation","type":"import","payload":{"progress":93}}
{"category":"creation","type":"import","payload":{"progress":97}}
{"category":"creation","type":"import","payload":{"progress":100}}
{"category":"creation","type":"import","payload":{"progress":100}}
{"category":"creation","type":"info","payload":{"message":"Downloading global GNSS resources ..."}}
{"category":"baseStation","type":"info","payload":{"message":"Importing local base stations ..."}}
{"category":"processing","type":"preprocess","payload":{"progress":0}}
{"category":"processing","type":"preprocess","payload":{"progress":0}}
{"category":"processing","type":"preprocess","payload":{"progress":0}}
{"category":"processing","type":"preprocess","payload":{"progress":5}}
{"category":"processing","type":"preprocess","payload":{"progress":5}}
{"category":"processing","type":"preprocess","payload":{"progress":11}}
{"category":"processing","type":"preprocess","payload":{"progress":17}}
{"category":"processing","type":"preprocess","payload":{"progress":17}}
{"category":"processing","type":"preprocess","payload":{"progress":23}}
{"category":"processing","type":"preprocess","payload":{"progress":23}}
{"category":"processing","type":"preprocess","payload":{"progress":28}}
{"category":"processing","type":"preprocess","payload":{"progress":28}}
{"category":"processing","type":"preprocess","payload":{"progress":31}}
{"category":"processing","type":"preprocess","payload":{"progress":31}}
{"category":"processing","type":"preprocess","payload":{"progress":35}}
{"category":"processing","type":"preprocess","payload":{"progress":35}}
{"category":"processing","type":"preprocess","payload":{"progress":39}}
{"category":"processing","type":"preprocess","payload":{"progress":39}}
{"category":"processing","type":"preprocess","payload":{"progress":43}}
{"category":"processing","type":"preprocess","payload":{"progress":46}}
{"category":"processing","type":"preprocess","payload":{"progress":50}}
{"category":"processing","type":"preprocess","payload":{"progress":53}}
{"category":"processing","type":"preprocess","payload":{"progress":58}}
{"category":"processing","type":"preprocess","payload":{"progress":62}}
{"category":"processing","type":"preprocess","payload":{"progress":64}}
{"category":"processing","type":"preprocess","payload":{"progress":67}}
{"category":"processing","type":"preprocess","payload":{"progress":71}}
{"category":"processing","type":"preprocess","payload":{"progress":75}}
{"category":"processing","type":"preprocess","payload":{"progress":79}}
{"category":"processing","type":"preprocess","payload":{"progress":85}}
{"category":"processing","type":"preprocess","payload":{"progress":89}}
{"category":"processing","type":"preprocess","payload":{"progress":93}}
{"category":"processing","type":"preprocess","payload":{"progress":93}}
{"category":"processing","type":"preprocess","payload":{"progress":93}}
{"category":"processing","type":"preprocess","payload":{"progress":100}}
{"category":"processing","type":"preprocess","payload":{"progress":100}}
{"category":"processing","type":"process","payload":{"backward":{"currentPass":1,"numPass":3,"passProgress":0,"progress":0},"forward":{"currentPass":1,"numPass":3,"passProgress":2,"progress":0}}}
{"category":"processing","type":"process","payload":{"backward":{"currentPass":1,"numPass":3,"passProgress":3,"progress":1},"forward":{"currentPass":1,"numPass":3,"passProgress":2,"progress":0}}}
{"category":"processing","type":"process","payload":{"backward":{"currentPass":1,"numPass":3,"passProgress":3,"progress":1},"forward":{"currentPass":1,"numPass":3,"passProgress":6,"progress":2}}}
.....

JSON Process File Path

The --process-file option is not affected by the --input option and if you provide a relative path, it will be from the calling process working directory.

Example Projects

You can find Qinertia CLI example projects on a dedicated GitHub repository. Please make sure to select the right demo package version according to the Qinertia CLI version you are running.

Download Example Projects

Download PDF

Command line

Introduction

CLI Concepts

Qinertia CLI application

CLI options

Environment Variables

Exit Codes

OEM Packaging

Software Updates

License & Authentication

User Information

Floating License

Node Locked

Using Internet

Install the license

Use the license

Revoke the license

Offline Mode

Generate the license

Use the license

Revoke the license

Processing a mission

Options

Example

Example Projects

Cookie Notice