Kit Kernel Command Line Options#

The command line options for Kit-kernel are listed below. This information can also be viewed by running kit.exe (Windows) or kit (Linux) without any command line options. These options are supported by all Kit based apps.

  • Logging & Debugging Options:

    • --help, -h: Displays the current help information for Kit-kernel. This includes the supported command line options and the general usage information for the app.

    • --info, -v: Enables more detailed ‘info’ level logging to stdout/stderr. This is the default log level for the log file even without this option being used, but the other log destinations (ie: stdout/stderr, debug console, Kit console window) default to ‘warn’ level. This can be used for debugging purposes to get more information out of the behavior of Kit extensions.

    • --verbose, -vv: Enabled even more detailed ‘verbose’ level logging to stdout/stderr. This can be used for debugging purposes to get even more information (above and beyond --info) out of the behavior of Kit extensions. Warning: this may produce very large log files!

    • --wait-debugger, -d: Suspends Kit-kernel execution until a debugger is attached to the process. The process will resume execution when either a debugger is attached or the user pushes any key to skip. The process will be suspended before loading any settings into the settings database but after the command line options are parsed. This same behavior may also be enabled by enabling the /app/waitForDebugger setting on the command line or in a loaded config file. If this setting is used instead of --wait-debugger, the process will be suspended later during startup after all settings have been processed and merged.

    • --allow-root: On Linux, this setting allows Kit-kernel to startup when running as the root user. If Kit is run as root without this option, it will exit immediately upon startup to avoid unintentionally setting the owner of created files as root which could cause them to become inaccessible to non-root users. Providing this setting signals to Kit that the user knows what they are doing and the launch as root is intentional. This same behavior can also be provided by setting the environment variable OMNI_KIT_ALLOW_ROOT to a non-zero value. This setting will be ignored on Windows.

  • Config, Data, and Log File Options:

    • --merge-config=<file>, -m=<file>: Merges an extra config file into Kit’s settings database on startup. This config file path may be given as an absolute or relative path. The file itself must be formatted as either JSON or TOML and may contain any number of settings.

    • --portable: Enable portable mode. This causes all log, user data/config, and cached files to be located relative to a specific root path (specified with --portable-root, defaults to the ${kit} path) instead of the user’s profile path. This is useful for debugging purposes to prevent debug changes from affecting the current user’s global settings.

    • --portable-root <PATH>: Implicitly enables portable mode and simultaneously specifies the path to use as the portable files root. All logs, user data/config, and cached files to be written to and read from this path instead of the user’s profile path. This is useful for debugging purposes to prevent debug changes from affecting the current user’s global settings.

    • --reset-user: Do not load persistent settings from user.config file.

    • --clear-data: Clear the ${data} folder before starting. The path that is cleared depends on whether portable mode is enabled or not.

    • --clear-cache: Clear the ${cache} folder before starting. The path that is cleared depends on whether portable mode is enabled or not.

  • Extension Management Options:

    • --enable <ID>: Enable the extension with the given ID. The extension ID may either be simply the extension’s full name (ie: omni.kit.telemetry) or its name plus a specific version (ie: omni.kit.telemetry-0.1.0). If the extension is not already present locally, it may be downloaded by the extension manager if downloads are enabled and allowed.

    • --ext-folder <PATH>: Adds a path to look for extra Kit extensions in. This may be a relative or absolute path. This option itself does not cause any specific extensions to be loaded but rather just provides an extra search path for extensions.

    • --ext-path <PATH>: Adds the direct path to a single Kit extension to be found. Note that this does not immediately enable the named extension but instead just adds it to the extension search path.

    • --publish <ID>: Causes a single Kit extension to be published to the online Kit extension registry during startup. This option may be used multiple times to publish multiple extensions. The Kit process will exit immediately after all named extensions have been published. The extension ID may either be an extension’s name or its name and version (as with the --enable option).

    • --publish-overwrite: Allow overwriting extension in registry when publishing. By default a publish operation will fail if the same extension version already exists in the extension registry. This option is ignored if the --publish option is not also used.

    • --unpublish <ID>: Unpublish an extension from the extension registry during startup. The Kit process will exit immediately after all named extensions have been unpublished. This option may be used multiple times to unpublish multiple extensions. The extension ID may either be an extension’s name or its name and version (as with the --enable option).

    • --update-exts: Look for the latest versions of each enabled extension in the extension registry and update each one that is found. Note that this will not replace an extension that is already at the latest version.

    • --list-exts: Lists all local Kit extensions and quit. This is useful for debugging purposes to see which extensions versions are present in all extension paths.

    • --list-registry-exts: List all extensions in the extension registry and quit.

    • --disable-ext-startup: Do not startup any extensions, only load them.

    • --ext-precache-mode: Only resolve and download all extensions then exit immediately afterward.

  • Script Launch Options:

    • --exec <SCRIPT> [[<ARGS>] ...], -e <SCRIPT> [[<ARGS>] ...]: Executes a specified Python script on startup. This is run after Kit-kernel has started up and all config files and command line settings have been merged into the settings database. Note that execution of this script may cause the execution of some extensions to be blocked. Once the script completes, the Kit process will exit. If the script’s path contains spaces, the full path must be quoted. If the script also has arguments, the entire script command must be quoted as well. Any arguments within the quoted string must also be quoted if they contain spaces. If the script path and arguments are not properly quoted, they will either be ignored by Kit or will be parsed in an unexpected way by Kit or Python when trying to launch the script.

Overriding Kit Settings#

Any Kit setting may also be specified on the command line. Command line settings will override settings found in config files in almost all cases. The only exception to that is the user’s privacy consent settings found in the privacy.toml file. If the privacy.toml file is present in the user’s ${omni_config} path, the settings in that file will always take precedence.

Any number of settings may be specified on the command line by passing an option that starts with --/ followed by the setting’s path and its new value. For example:

--/app/printConfig=true

Settings may have boolean, floating point, integer, or string values. Note that some settings expect a specific data type and may not function correctly if given an unexpected value.

To view the settings (and their values) that are merged into the settings database on Kit-kernel startup, the --/app/printConfig option may be used. This will write the full settings database to stdout as JSON formatted data.

Using Environment Variables for Setting Values#

Settings provided on the command line or in config files may also get their values from environment variables. This may be done by giving the setting a value that contains the environment variables name like this:

  • On the command line:

--/app/printConfig=$env{PRINT_CONFIG_SETTING}

  • In a TOML config file:

[app]
printConfig = "$env{PRINT_CONFIG_SETTING}"

In this example, the /app/printConfig will be given the value of the environment variable PRINT_CONFIG_SETTING. There are no restrictions on the formatting of the environment variable name. The variable’s value should however be compatible with what the setting expects (ie: boolean, floating point, integer, or string).

This method of providing values to settings is useful in situations where the Kit based app is deployed in a container. This allows the values of settings in the container itself to be hard coded to reference an environment variable so that users launching the container can modify launch behavior simply by passing specific environment variables to the container.

Note that this environment variable value replacement for settings is only performed once on Kit-kernel startup. The named environment variable is expected to exist before startup. If the named environment variable does not exist, the setting will be given an empty string as its value and may cause unexpected behavior.

Overriding Settings With Envorinment Variables#

The values of settings in config files can also be overridden using environment variables with specific names. These environment variables do not need to have their names listed in settings like the above method does. Instead, any environment variable that exists at startup time that begins with OMNI_KIT_ followed by the setting’s full path (with path separators replaced by underscores) will override any other value given for that setting. Note that case is important in the variable’s name.

For example, the /app/printConfig setting can be overridden with the environment variable OMNI_KIT_app_printConfig.

Setting value overrides with these environment variables will only be checked once on Kit-kernel startup. These will also only override settings given in config files. Settings given on the command line will still override these environment variables if they exist.

Note that any setting value can be set by this, similarly to the commandline overrides, but settings that are initialized after startup will overwrite anything set by environment variables. In the case where an environment variable is misspelled (e.g. OMNI_KIT_lgo_level), there will be no warnings issued since this is a valid setting.