Introduction

The uMod Agent is an open-source command-line tool designed to help server administrators install, update, and manage servers and plugins.

Global options

Global options are available with every command

• --working-directory=PATH (--dir):
  Use the specified directory as the working directory (instead of the current directory)
• --help (-h): Display help information
• --no-input: Disable console interaction
• --verbose (-v): Increase verbosity of message output
• --quiet (-q): Disable console output

Install

The install command installs a game server and server-related packages.

umod install <gameName>

Options

• --strict: Exit with non-zero exit code in case of error
• --force: Force install to overwrite local changes without prompt
• --lock: Skip install and only install into the lock file (useful to suppress hash mismatch warnings)
• --validate: Validate install after it is complete
• --filter=all (-f): Filter what to install
  - all: (default)
  - game, server: Game server only
  - umod: uMod core and apps
  - core: uMod core only
  - apps: uMod apps only

[game]

• --game=VALUE (-g): The name of the game to install
• --username=VALUE (-u): The Steam username to authenticate
• --password=VALUE (-p): The Steam password
• --branch=VALUE (-b): The game branch
• --branch-password=VALUE:
  The branch password
• --skip-dd (--sd): Skip game file handling and only update game lock file
• --os=default: The operating system to download for
  - windows, macos, linux, default
• --prerelease (-P): Use pre-release branch (for packages)
• --filelist: Specify path to file containing list of files to download
  --filelist=temp.txt
• --files=VALUE: Specify file pattern, file name, or directory to download (wilcards accepted, comma delimited)
  --files=*.mp4, --files=Managed/*
• --skip=VALUE: Specify file pattern, file name, or directory to skip (wilcards accepted, comma delimited)
  --skip=*.mp4,*.bundle, --skip=Managed/*

Update

The update command will keep the game server and all of the installed packages and plugins up to date (usually with the latest version).

umod update

Update the entire server installation including the latest server files, packages, and plugins.

umod update <gameName>

Narrow down what to update by specifying a game, package, or plugin.

umod update plugins

Or update only a particular category of resource...

Options

• --strict: Exit with non-zero exit code in case of error
• --force: Force update to overwrite local changes without prompt
• --lock: Skip update and update only the lock file (useful to suppress hash mismatch warnings)
• --validate: Validate update after it is complete
• --patch-available: Skip game update if corresponding patched assemblies are not available
• --filter=all (-f): Filter what to update
  - all: (default)
  - game, server: Game server only
  - umod: uMod core and apps
  - core: uMod core only
  - apps: uMod apps only

[plugin] [version] [...]

[game]

• -u, --username=VALUE: The Steam username to authenticate
• -p, --password=VALUE: The Steam password
• -b, --branch=VALUE: The game branch
• --branch-password=VALUE : The branch password
• --skip-dd (--sd): Skip game file handling and only update game lock file
• --os=default: The operating system to download for
  - windows, macos, linux, default
• --prerelease (-P): Use pre-release branch (for packages)
• --filelist: Specify path to file containing list of files to download
  --filelist=temp.txt
• --files=VALUE: Specify file pattern, file name, or directory to download (wilcards accepted, comma delimited)
  --files=*.mp4, --files=Managed/*
• --skip=VALUE: Specify file pattern, file name, or directory to skip (wilcards accepted, comma delimited)
  --skip=*.mp4,*.bundle, --skip=Managed/*

Require

The require command installs new plugins into the umod/plugins directory.

umod require MyPlugin 2.*

If a version is not specified, the default version mask will use the latest major version.

Options

• --strict: Exit with non-zero exit code in case of error
• --force: Force require
• --lock: Skip require and update only the lock file (useful to suppress hash mismatch warnings)

[plugin] [version] [...]

Remove

The remove command removes plugins (and packages) from the server.

[plugin] [...]

Show

The show command will list all available packages.

umod show

Filter the list by searching by name (with wildcards)

umod show core/*

View individual package details by passing the full package name

umod show core/webclient

Options

• --format=: Choose between json or CLI output
• --names (-n): List only package or plugin names
• --path: List only package or plugin paths
• --tree (-t): List dependencies with tree output

[game]

• --game (-G): List only game related information
• --prerelease (-P): Use pre-release branch

[plugin]

• --plugin=name (--plugins): List only plugin related information

[package]

• --package=name (--packages): List only package related information
• --prerelease (-P): Use pre-release branch

Obsolete and old

The obsolete command shows a list of installed plugins and packages with updates available.

Options

• --recursive: Resolves all dependencies recursively
• --tree: Prints results with a nested tree
• --prerelease (-P): Use pre-release branch
• --minor-only (-m): Show plugins and packages with minor semver-compatible updates
• --strict (-s): Exit with non-zero exit code in case of error
• --format=VALUE: Choose between json or CLI output

[game]

[package] [...]

[plugin] [...]

Suggests

The suggests command lists any plugins suggested by other installed plugins.

Options

• --recursive: Resolves all dependencies recursively
• --format=VALUE: Choose between json or CLI output

[plugin] [...]

Fund

Help the developers who maintain your dependencies. The fund command lists all the donation links from installed plugins.

Depends

The depends command lists any plugin that depend on a specified plugin

Options

• --recursive: Resolves all dependencies recursively
• --format=VALUE: Choose between json or CLI output

[plugin]

Prohibits

The prohibits command lists any plugins that are blocking a specified plugin from being installed.

Options

• --recursive: Resolves all dependencies recursively
• --format=VALUE: Choose between json or CLI output

[plugin]

Validate

The validate command ensures the lock signature matches the current installation and that version constraints are resolved without error.

Options

• --strict (-s): Exit with non-zero exit code in case of error
  Exit codes:
  1 - warnings (with --strict)
  2 - errors
  0 - valid
• --filter=all (-f): Filter what to validate
  - all: (default)
  - game, server: Game server only
  - umod: uMod core and apps
  - core: uMod core only
  - apps: uMod apps only

Status

The status command lists any plugins or packages which have local changes.

Options

• --strict (-s): Strict status check, hash mismatch results in non-zero exit code
• --format=VALUE: Choose between json or CLI output
• --filter=all (-f): Filter what to display the status of
  - all: (default)
  - game, server: Game server only
  - umod: uMod core and apps
  - core: uMod core only
  - apps: uMod apps only

[game]

[plugin]

[package]

Config

The config command displays and modifies .toml configuration files and the global uMod Agent configuration.

Options

• --remove (-r): Removes an option if possible

• file: Show the contents of a file

• file.option [value]: Display or modify an option in a file

umod config agent.progress_bars 0

Licenses

The licenses command lists the name and license of every installed plugin.

Options

• --format=VALUE: Choose between json or CLI output

Cache

The cache command will describe the current state of the global package cache

Options

• --clear: Clear the global package cache
• --old: Used with "clear", will clear packages older than a 30 days.

Help

Find details about commands with the help command.

umod help

umod help install

Exit codes

When using --strict option, the uMod agent process will exit with a code indicating to the calling process whether the requested command succeeded or failed.

• 0: OK
• 1: Generic/unknown error code
• 2: Dependency solving error code / No update needed

The above exit codes may be used to improve integrations with third-party tools and scripts.