BUTR's Nexus Mods File Uploader

Now powered by the official Nexus Mods v3 API!

Introduction

This is a small command-line tool that can be used to upload mod files to an existing mod on Nexus Mods.

As of v4.0.0, this tool uses the official Nexus Mods v3 API — the same API used by the official Nexus-Mods/upload-action GitHub Action. Everything works with just your API key, which you can get from your API keys page.

Breaking changes in v4.0.0

Session cookie support was deprecated and removed — the official API only requires an API key:

• The refresh command has been removed.
• The -s/--session-cookie option and the UNEX_SESSION_COOKIE/UNEX_COOKIES variables have been removed from all commands, including check.

If your pipeline still passes any of these, remove them.

It also supports adding/updating changelogs.

Installation

You can either download the binary for your platform from the Releases section on the right, or install it using the dotnet CLI:

dotnet tool install -g BUTR.NexusUploader
# then run with
unex

If your project already has a local tools manifest, you can also install it locally:

dotnet tool install BUTR.NexusUploader
# then run with
dotnet unex

By default, your mod's main version will be updated to your new file version, but you can skip this using the --no-version-update option.

You can optionally upload your file as a new version of an existing file, in one of three ways:

• --file-id (or UNEX_FILEID): the v3 mod file ID (the update chain ID, as used by the official upload-action). The new version is added to that chain directly, no lookups needed.
• PreviousFile set to a file ID: the game-scoped file ID as shown on the mod page's Files tab. It is resolved to its update chain via the API.
• PreviousFile set to "auto": the highest-versioned Main File on your mod is updated.

If none of these are set, a brand new file will be created on the mod page.

Configuration and Usage

Since there's a lot of information required when updating mods, the recommended method is to create a configuration file for non-sensitive information and use environment variables just for the sensitive information. That being said, you can mix-and-match keys from the config file or environment variables (just prefix them with UNEX_) at will.

Sample unex.yml:

Game: site
ModId: 163
FileName: Upload Test
FileDescription: |-
  Your file description should go here.

  You can include whatever you like in your description, it's added as-is.

You can also use a JSON configuration file if you prefer, you heathen

The only sensitive configuration key is your Nexus Mods API key, which should be in the UNEX_APIKEY environment variable. You can find or generate your API key on your API keys page.

The v3 API base URL can be overridden with the UNEX_API_BASE or NEXUSMODS_API_BASE environment variable (defaults to https://api.nexusmods.com/v3).

Then, call the CLI to begin your upload:

#unex upload <mod-id> <path-to-file> -v <target-version>
unex upload 163 ./Your-Mod-File.zip -v 1.1.2

Available Commands:

unex -h

USAGE:
    unex [OPTIONS] <COMMAND>

EXAMPLES:
    unex changelog <version> -c <changelog>
    unex upload <mod-id> <archive-file> -v <version>
    unex check -k <api-key>

OPTIONS:
    -h, --help    Prints help information

COMMANDS:
    changelog <version>               Add a changelog entry for a specific mod version
    upload <mod-id> <archive-file>    Upload a mod
    check                             Check the validity of an API Key

---

unex changelog -h

DESCRIPTION:
Add a changelog entry for a specific mod version

USAGE:
    unex changelog <version> [OPTIONS]

EXAMPLES:
    unex changelog <version> -c <changelog>

ARGUMENTS:
    <version>    The version of the mod to update the changelog for

OPTIONS:
    -h, --help                     Prints help information
    -k, --api-key                  The NexusMods API key. Available Environment Variable: UNEX_APIKEY
    -g, --game                     The NexusMods game name (domain) to upload the mod to. Can be found in the URL of the game page. Available Environment Variable: UNEX_GAME
    -m, --mod-id                   The NexusMods mod Id to update the changelog for. Available Environment Variable: UNEX_MODID
    -c, --changelog <CHANGELOG>    The changelog content to add. Available Environment Variable: UNEX_CHANGELOG

---

unex upload -h

DESCRIPTION:
Upload a mod

USAGE:
    unex upload <mod-id> <archive-file> [OPTIONS]

EXAMPLES:
    unex upload <mod-id> <archive-file> -v <version>

ARGUMENTS:
    <mod-id>          The NexusMods mod Id to upload the file to
    <archive-file>    Path to the mod archive file to upload

OPTIONS:
    -h, --help                                    Prints help information
    -k, --api-key                                 The NexusMods API key. Available Environment Variable: UNEX_APIKEY
    -g, --game                                    The NexusMods game name (domain) to upload the mod to. Can be found in the URL of the game page. Available Environment Variable: UNEX_GAME
    -f, --file-name                               Name for the file on NexusMods. Available Environment Variable: UNEX_FILENAME
    -v, --version <VALUE>                         Version for your uploaded file. May also update your main version. Available Environment Variable: UNEX_FILEVERSION
        --category                                Category for the file on NexusMods: main, optional or miscellaneous. Available Environment Variable: UNEX_FILECATEGORY
        --file-id                                 The NexusMods v3 mod file Id (update chain) to add the new version to. Takes precedence over PreviousFile. Available Environment Variable: UNEX_FILEID
        --remove-download-with-manager [VALUE]    Removes the Download With Manager button. Available Environment Variable: UNEX_REMOVEDOWNLOADWITHMANAGER
        --no-version-update [VALUE]               Skips updating your mod's main version to match this file's version. Available Environment Variable: UNEX_SKIPMAINVERSIONUPDATE
        --set-main-vortex [VALUE]                 Sets this file as the main Vortex file (for the Download with Manager buttons). Available Environment Variable: UNEX_SETMAINVORTEXFILE
        --archive-existing [VALUE]                Archives the existing file when the new version is added. Available Environment Variable: UNEX_ARCHIVEEXISTING

---

unex check -h

DESCRIPTION:
Check the validity of an API Key

USAGE:
    unex check [OPTIONS]

EXAMPLES:
    unex check -k <api-key>

OPTIONS:
    -h, --help       Prints help information
    -k, --api-key    The NexusMods API key. Available Environment Variable: UNEX_APIKEY

---