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 arguments

You can display a full help that lists all available options and arguments 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:
    --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>
    --profile <file> (Env:QINERTIA_CLI_PROCESS_PROFILE)
                                          Path to application profile file
    --overwrite-output                    Overwrite existing outputs
  [Option Group: authentication]

    [At most 1 of the following options are allowed]
    [Option Group: api-key]
      Options:
        --api-key <key> REQUIRED (Env:QINERTIA_CLI_PROCESS_API_KEY)
                                              API Key.
        --secret <secret> REQUIRED (Env:QINERTIA_CLI_PROCESS_API_KEY_SECRET)
                                              API Key secret.

login
  Authenticates with user/pass, caching the auth token.
  [Option Group: authentication]

    [At most 1 of the following options are allowed]
    [Option Group: api-key]
      Options:
        --api-key <key> REQUIRED              API Key.
        --secret <secret> REQUIRED            API Key secret.

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_USER_INFO_STATUS_OUTPUT)
                                          A pipe name, stdout or stderr

update
  Handle Qinertia updates.
  Options:
    --check REQUIRED                      Check if update is available.
    --status-output <name> (Env:QINERTIA_CLI_UPDATE_STATUS_OUTPUT)
                                          A pipe name, stdout or stderr

profile-skeleton
  Generate an application profile skeleton.
  Options:
    -o,--output <file> (Env:QINERTIA_CLI_PROFILE_SKELETON_OUTPUT_FILE)
                                          Path to output skeleton file. Default to 'profile.skeleton.json'.
  [Option Group: authentication]

    [At most 1 of the following options are allowed]
    [Option Group: api-key]
      Options:
        --api-key <key> REQUIRED              API Key.
        --secret <secret> REQUIRED            API Key secret.

host-id
  Prints licensing host id.

roam
  Get an offline Qinertia license.
  Options:
    --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.
  [Option Group: authentication]

    [At most 1 of the following options are allowed]
    [Option Group: api-key]
      Options:
        --api-key <key> REQUIRED              API Key.
        --secret <secret> REQUIRED            API Key secret.

revoke
  Revoke a checked out offline Qinertia license.
  Options:
    --license <license>                   License file. If not provided, the global Qinertia checked out license will be revoked.
  [Option Group: authentication]

    [At most 1 of the following options are allowed]
    [Option Group: api-key]
      Options:
        --api-key <key> REQUIRED              API Key.
        --secret <secret> REQUIRED            API Key secret.

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

CLI subcommands

The CLI is organized around subcommands for each type of action that can be performed. Please find below a short description of each subcommands:

Subcommand	Description
`process`	Main command used to process a project. See Processing a Mission for more information.
`profile‑skeleton`	Generates a json skeleton file used to provide user profile related options such as CORS credentials. See Profile Skeleton (CLI) page.
`update`	System command used to easily check if Qinertia software is up-to-date. Check Software Update for more information.
`login`	Authenticate the user either using interactive user/pass prompt or an API key. Cache locally credentials to re-use them easily in further qinertia-cli calls. Please read License & Authentication (CLI) for detailed information about login and licenses.
`logout`	Logout any connected user and clear locally cached credentials.
`user‑info`	Returns user account information and fetched/active license for any locally cached credentials.
`host-id`	Display the computer unique host id that can be used to generate on MySBG a node locked offline license.
`roam`	Request to MySBG license server a node locked offline license file automatically (internet connection required).
`revoke`	Revoke a node locked offline license: If there is no internet connection, the license is removed locally and a revoke key is displayed to release the license on MySBG. If there is an internet connection, the license is automatically released on MySBG.
`last‑revoke‑key`	Display the latest revoke key as returned by the revoke command for manual node locked offline license release on MySBG.

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

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.

A valid license is also required to process data, please please read the License & Authentication (CLI) page to get more details on this topic.

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
--license		Optionally specify a license id to use, this is only relevant if you have more than one valid Qinertia license for your organization.
--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.
--process-file		Path to the JSON Process file that describe the job to execute.
--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.
--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. If not specified, relative paths are referenced to the processing JSON file.
--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.
--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.
--profile		Path to a profile JSON file used to provide CORS providers credentials and user preferences. See Profile Skeleton (CLI) page.
--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.
--api-key		For machine to machine integration, provide an API Key to authenticate via MySBG and fetch the license. If not provided, Qinertia will automatically prompt the user to log in when necessary.
--secrect		Mandatory when --api-key is used, provides the API Key secert. Please check License & Authentication (CLI).

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