CLI options

Reference for Korall Engineering™ command-line arguments and options: the options every application accepts, the options of Agent, Remote and HUB, and the options of the other applications.

Tip

For a test run, give the application its own data directory with --base-dir <path>. The run then has its own settings, keys and logs, and your own nodes stay as they are.

---

Overview

Agent, Remote, HUB, Zoo and the windowed applications share one list of options. Each application acts on the options that apply to it, and accepts the others. An option that takes a value accepts --name value and --name=value.

The applications do not all treat an option that they do not know in the same way:

• Agent, Remote and HUB print Command line error: and the reason on standard error, and then start as usual.
• Zoo, Paint, Auda, Bahn, Singularity and the Construct editor print the same line and Try --help for the list of options., and stop with exit code 1.

---

Common options

Options available for all Korall Engineering™ applications:

Help and version

Data and identity options

When you give more than one passphrase option, --hive-passphrase-stdin wins, then --hive-passphrase-file, then --hive-passphrase.

Window and startup options

Network options

Logging options

System options

---

HUB-specific options

Options that only the HUB (fleet management) application acts on:

---

Other applications

Zoo

The Zoo has no window. It acts on --local-port, --base-dir, --head-less, --log-detail, --log-color and the help and version options.

Construct and the windowed applications

The Construct editor, Paint, Auda, Bahn and Singularity act on --base-dir, --user-data, --head-less, --fullscreen, --opal, --close-on-completion, the system options and the graphics and diagnostics options. Construct also has subcommands and export options of its own. See Construct CLI.

---

MockNode options

MockNode is the test application for node behaviour. It has two modes.

Node mode

With --personality, MockNode runs one test node. The node keeps its data in the directory of that personality, and MockNode makes the personality when it does not exist.

The node also accepts the common options.

Manager mode

Without --personality, MockNode opens the manager of test personalities and constellations.

Manager mode also accepts the global graphics and logging options, such as --rhi-backend and --log-color. Any other option stops it with an error and exit code 1.

---

Usage examples

Basic usage

# Start Agent with its own data directory
agent --base-dir /tmp/agent-test

# Start Agent with the identity of one node
agent --node-id <node-identity-id>

# Start Agent with verbose logging
agent --log-detail verbose

Network configuration

# Use another Zoo server
agent --zoo-url https://zoo.example.com/api

# Start the Zoo on another port
zoo --local-port 9000

Development and testing

# Run without a window
hub --head-less

# Start in one activity and quit when its task is complete
remote --activity <activity-name> --close-on-completion

# More log detail for two categories
agent --log session:full,scheduling:summary

MockNode testing

# Create a test Agent
mocknode --personality TestAgent --type agent

# Create a test Remote
mocknode --personality TestRemote --type remote

# Run a manager script and exit
mocknode --run-script test_scenario --no-gui

---

Graphics and diagnostics options

Every application accepts these before or after its own options. They are flags, not environment variables. The graphics ones are explained in Graphics backend. The diagnostic ones are explained in Collect useful logs.

Developer options

---

Qt platform options

Standard Qt options are also available:

Display options

Agent, Remote and HUB read their own options before Qt does, so a Qt option can print a Command line error: line. The application still starts, and Qt still applies the option.

Common platforms

Examples

# Force Wayland
agent -platform wayland

# Use custom style
agent -style fusion

# Headless mode
agent -platform offscreen

---

Precedence

Apart from NO_COLOR and CLICOLOR_FORCE, which --log-color overrides, the applications read no environment variables. An option comes from the command line, the settings file or the default:

1. Command-line options (highest)
2. Settings file
3. Default values (lowest)

---

Exit codes

Korall Engineering™ applications return these exit codes:

Construct's subcommands have exit codes of their own. See Construct CLI.

Checking exit code

zoo --local-port 9000
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
    echo "Exited normally"
else
    echo "Error: $EXIT_CODE"
fi

---

Configuration file integration

Persisting options

A command-line option applies to one run, and the application does not save it. To keep a value, set it in the settings. --debug-control is the one exception: the node saves its value.

# One run with verbose logging
agent --log-detail verbose

# For every run, set Log detail to verbose in the settings

---

Script integration

Bash script

#!/bin/bash
# start_agent.sh - Start Agent with custom configuration

BASE_DIR="${1:-/tmp/agent-test}"
LOG_DETAIL="${2:-normal}"

exec agent \
    --base-dir "$BASE_DIR" \
    --log-detail "$LOG_DETAIL"

Systemd service

# /etc/systemd/system/hub.service
[Unit]
Description=HUB
After=network.target

[Service]
Type=simple
User=hub
ExecStart=/usr/bin/hub \
    --head-less \
    --base-dir /var/lib/hub \
    --log-color never
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Docker

FROM ubuntu:22.04

COPY hub /usr/bin/

ENTRYPOINT ["hub"]
CMD ["--head-less", "--base-dir", "/data"]

# Run with custom options
docker run hub --head-less --base-dir /data --log-detail verbose

---

Debugging options

Verbose output

# Every log category, Qt's own too
agent --log-detail verbose

# Full detail for one category only
agent --log session:full

Version information

agent --version
# agent 1.2.3

---

Option reference table

Complete option reference for the options that every application shares. The graphics and diagnostics options, the HUB-specific options and the MockNode options are in their own sections.

---