ProgramArgs — Runtime CLI Arguments

Oidis applications accept command-line arguments that control runtime behavior such as debug mode, verbose logging, server lifecycle, and database operations. The ProgramArgs class parses these arguments and exposes them through getter/setter methods accessible anywhere in the application.

Access

import { Loader } from "../Loader.js";

const args = Loader.getInstance().getProgramArgs();

if (args.IsDebug()) {
    // debug-specific behavior
}

Every getter method on ProgramArgs also acts as a setter when called with an argument: args.IsDebug() reads the value, args.IsDebug(true) sets it.

Class Hierarchy

ProgramArgs has a two-level inheritance chain:

Package	Class	Adds
io-oidis-localhost	ProgramArgs	Core flags (debug, verbose, server control, integrity checks)
io-oidis-hub	ProgramArgs extends Parent	Hub-specific flags (agent mode, DB reset)

Solution projects (e.g. IRMA) that extend Hub automatically inherit both levels. If a solution needs custom CLI flags, it can extend Hub's ProgramArgs and override processArg().

Localhost Flags (Base)

These flags are available in all Oidis applications (localhost and hub-based).

Basic Options

Flag	Short	Method	Description
--help	-h, /h, /?, help, ?	IsHelp()	Print help and wait for input
--version	-v, /v, version	IsVersion()	Print application name and version
--path	-p, /p, path	IsPath()	Print project base directory
--debug		IsDebug()	Enable debug mode
--verbose		IsVerbose()	Enable verbose output
--test-run		IsTestRun()	Mark as test run (also checks IS_WUI_TEST_RUN env var)
--log-level=N		LogLevel()	Set numeric log level

Server Control

Flag	Method	Description
start	StartServer()	Start the server
stop	StopServer()	Stop a running server
restart	RestartServer()	Restart the server
list-routes	ListRoutes()	Print all registered routes

Integrity & Configuration

Flag	Method	Description
--selfcheck	IsSelfCheck()	Run self health check (pings the running server)
--update-verify	IsUpdateVerify()	Self-update: a freshly downloaded release proves it boots (Loader.verifyRelease()), exit 0 or 1
--update-activate	IsUpdateActivate()	Self-update: detached activator switching the service installation to a verified release
--update-root=, --update-new=, --update-old=, --update-appdata=	getUpdateArgs()	Install root, new release, rollback release and appData of the activation
--integrity-check	IsIntegrityCheck()	Run assembly integrity check
--ignored-checks=a,b,c	getIgnoredChecks()	Comma-separated list of integrity checks to skip
--target=path	TargetBase()	Target HTML file for localhost hosting
--with-mapping / --elastic-mapping	ElasticMapping()	Trigger Elasticsearch mapping

Path Accessors

These are not CLI flags but programmatic accessors set during application bootstrap:

Method	Description
ProjectBase()	Root directory of the project
BinBase()	Binary/executable base directory
TargetBase()	Build target base directory
AppDataPath()	Application data directory (downloads, temp files, etc.)

Hub Flags (Extended)

Hub-based applications add two flags on top of the localhost base:

Flag	Method	Description
--agent	IsAgent()	Run as agent instance (secondary role in multi-instance setup)
--reset-db	WithDBReset()	Force database synchronization on startup

Debug Mode

--debug enables debug mode which affects several runtime behaviors:

• Puppeteer: Runs browsers in headed mode (visible window) instead of headless. Controlled via IPuppeteerExtractOptions.debug:

  private getExtractOptions() : IPuppeteerExtractOptions {
      return {debug: Loader.getInstance().getProgramArgs().IsDebug(), verbose: false};
  }

• Logging: Extended debug log output via LogIt.Debug() calls throughout the application

Without --debug, Puppeteer runs headless and debug-level log messages are suppressed.

Usage Examples

# Start server normally (headless, production-like)
node loader.min.js start

# Start in debug mode (Puppeteer headed, verbose logging)
node loader.min.js start --debug

# Start with verbose output and custom log level
node loader.min.js start --verbose --log-level=3

# Start as agent with DB reset
node loader.min.js start --agent --reset-db

# Print version and exit
node loader.min.js --version

# Run integrity check, skipping specific checks
node loader.min.js --integrity-check --ignored-checks=check1,check2

# List all registered routes
node loader.min.js list-routes

Argument Format

ProgramArgs.Normalize() pre-processes raw CLI arguments into a consistent format before parsing. It supports:

• Long flags: --debug, --log-level=3
• Short flags: -h, -v, -p
• Windows-style: /h, /v, /p (single character only)
• Bare commands: start, stop, restart, help, version, path, list-routes
• Key-value pairs: --target=path/to/file, --log-level=3, --ignored-checks=a,b,c
• Quoted values: --target="path with spaces", --target='path with spaces'

Argument Parsing

Normalize()

Normalises a raw process.argv-style array by pairing flag keys with their values. Handles:

• --key=value (equals assignment)
• --key value (space-separated)
• /k (Windows single-char style)
• Quoted values with internal spaces: --key "my value" → stored as "my value"

public Normalize($args : string[]) : string[]

Parse()

Parses and applies a normalised argument list. Called once at startup with the full process.argv array.

public Parse($args : string[]) : void

When no arguments are provided, IsHelp(true) is set automatically (shows help prompt).

---

Stdin Handler

When IsHelp(), IsVersion(), or IsPath() are true, the application prints output and prompts for input via StdinManager. A custom handler can be set before Parse() to intercept that input:

Loader.getInstance().getProgramArgs().setStdinHandler(($input : string) : void => {
    // re-parse the user-entered arguments
    Loader.getInstance().getProgramArgs().Parse($input.split(" "));
});

---

Extension: Custom Args

To add custom arguments, extend ProgramArgs and override processArg():

export class MyProgramArgs extends ProgramArgs {

    private myFlag : boolean = false;

    public MyFlag($value? : boolean) : boolean {
        return this.myFlag = Property.Boolean(this.myFlag, $value);
    }

    protected processArg($key : string, $value : string) : boolean {
        switch (StringUtils.ToLowerCase($key)) {
        case "--my-flag":
            this.MyFlag(true);
            return true;
        default:
            return super.processArg($key, $value);
        }
    }
}

Register the custom class in EnvironmentArgs by returning it from createProgramArgs().

---

See also: Architecture Overview | Property | Commons Config