Skip to main content

ephervex mod

Manage and troubleshoot mods in client instances and local servers

Usage and options​

Manage and troubleshoot mods in client instances and local servers

Usage: ephervex mod [OPTIONS] <COMMAND>

Commands:
  search        Search a mod catalog for mods that fit a client or a server
  show          Show a mod and the versions available for a client or a server
  plan          Show what installing a mod would involve, without installing it
  install       Install a mod and everything it requires
  catalog       Show or set which catalog mod commands use when none is named
  list          List the mods installed into an instance through a provider
  verify        Check that every file a client or server records is there, with the right bytes
  repair        Replace every file a client or server is missing or holding wrongly
  dependencies  Show what each mod needs, and what needs it
  refresh       Ask each catalog what a client's or server's mods need, and record the answers
  isolate       Narrow a reproducing mod set by testing dependency-safe configurations
  delete        Take a mod's jar off disk, keeping the record that wants it
  enable        Let a mod load again after it was disabled
  disable       Keep a mod installed but stop the loader from loading it
  help          Print this message or the help of the given subcommand(s)

Options:
      --json  Emit machine-readable JSON where the command supports it
  -h, --help  Print help
Search a mod catalog for mods that fit a client or a server.

Results are judged against the exact Minecraft version and loader of the instance or server you name. Searching for a server leaves out mods that declare they do not run on one.

Usage: ephervex mod search [OPTIONS] <--instance <INSTANCE>|--server <SERVER>> <QUERY>

Arguments:
  <QUERY>
          What to search for

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --provider <PROVIDER>
          Which catalog to search. Defaults to your preferred catalog

          [possible values: modrinth, curseforge]

      --limit <LIMIT>
          Show at most this many results, from 1 to 25. A larger number shows 25

          [default: 10]

      --offset <OFFSET>
          Skip this many results, to page further into a long list

          [default: 0]

      --include-incompatible
          Also list mods that do not fit, with the reason each one does not.

          They are shown so you can see why the mod you were looking for is not offered. They still cannot be installed. For a server this includes mods that only run on a client.

  -h, --help
          Print help (see a summary with '-h')

ephervex mod show​

Show a mod and the versions available for a client or a server

Usage: ephervex mod show [OPTIONS] <--instance <INSTANCE>|--server <SERVER>> <PROJECT>

Arguments:
  <PROJECT>  The mod, by its project id or slug in the chosen catalog

Options:
      --instance <INSTANCE>   The client instance to operate on
      --json                  Emit machine-readable JSON where the command supports it
      --server <SERVER>       The dedicated server to operate on
      --provider <PROVIDER>   Which catalog the mod is on. Defaults to your preferred catalog [possible values: modrinth, curseforge]
      --include-incompatible  Also list versions that do not fit, with the reason each one does not
  -h, --help                  Print help

ephervex mod plan​

Show what installing a mod would involve, without installing it.

Reports the version that would be installed, every dependency that comes with it, and the optional ones you could add. Writes nothing.

Usage: ephervex mod plan [OPTIONS] <--instance <INSTANCE>|--server <SERVER>> <PROJECT>

Arguments:
  <PROJECT>
          The mod, by its project id or slug in the chosen catalog

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --provider <PROVIDER>
          Which catalog the mod is on. Defaults to your preferred catalog

          [possible values: modrinth, curseforge]

      --version <VERSION>
          Install this exact version instead of the newest compatible one.

          Preserved exactly. If it does not fit the instance or server, the install is refused rather than moved to a nearby release.

      --optional <PROJECT>
          Also install this optional dependency, by its project id.

          Repeatable. Optional dependencies are left out unless named here.

  -h, --help
          Print help (see a summary with '-h')

ephervex mod install​

Install a mod and everything it requires.

The newest version that fits the instance or server is chosen unless you name one. Required dependencies are installed with it; optional ones are not, unless you ask for them.

Installing onto a server touches that server only, and works with no linked client. A mod that runs only on a client is refused, and a required dependency that runs only on a client is installed with a warning because the mod that needs it cannot load without it. A running server picks the change up on its next start.

Usage: ephervex mod install [OPTIONS] <--instance <INSTANCE>|--server <SERVER>> <PROJECT>

Arguments:
  <PROJECT>
          The mod, by its project id or slug in the chosen catalog

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --provider <PROVIDER>
          Which catalog the mod is on. Defaults to your preferred catalog

          [possible values: modrinth, curseforge]

      --version <VERSION>
          Install this exact version instead of the newest compatible one.

          Preserved exactly. If it does not fit the instance or server, the install is refused rather than moved to a nearby release.

      --optional <PROJECT>
          Also install this optional dependency, by its project id.

          Repeatable. Optional dependencies are left out unless named here.

      --accept-unknown-server-support
          Install onto a server even when the catalog does not say whether the mod, or a mod it needs, runs on a server.

          Without it, such an install is refused and the mods are named.

      --use-installed <PROJECT>
          Let a jar already in the mods folder stand in for the dependency with this project id, when that jar provides the same mod.

          Repeatable. The dependency is still downloaded and checked, and is left out only if one jar already there declares every mod id it does. On a server it then needs no --accept-unknown-server-support. Without it, a dependency that another jar already provides is refused, because the game does not start with two copies of one mod.

  -h, --help
          Print help (see a summary with '-h')

ephervex mod catalog​

Show or set which catalog mod commands use when none is named.

The same setting the desktop app's mod browser opens on. Local only: naming a catalog records a preference and contacts nothing, and a CurseForge API key is still needed at the moment a CurseForge request is actually made.

Usage: ephervex mod catalog [OPTIONS] [CATALOG]

Arguments:
  [CATALOG]
          The catalog to prefer. Omit to show the current setting

          [possible values: modrinth, curseforge]

Options:
      --clear
          Go back to Ephervex's own default catalog

      --json
          Emit machine-readable JSON where the command supports it

  -h, --help
          Print help (see a summary with '-h')

ephervex mod list​

List the mods installed into an instance through a provider.

Jars you placed in the mods folder yourself are not listed: Ephervex has no project or version for them and does not guess at one.

Usage: ephervex mod list [OPTIONS] <INSTANCE>

Arguments:
  <INSTANCE>
          The client instance to list

Options:
      --json
          Emit machine-readable JSON where the command supports it

  -h, --help
          Print help (see a summary with '-h')

ephervex mod verify​

Check that every file a client or server records is there, with the right bytes.

The recipe already carries the digest each provider published, so this reaches no network and changes nothing. It answers the question looking for the file cannot: a jar truncated by a full disk, or left half written when a machine lost power, is present and still wrong.

A file the recipe records no digest for is reported as unproven rather than sound or broken. A pack that shipped a jar inside itself, rather than pointing at one, published no hash for it and never will.

Usage: ephervex mod verify [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --shared
          Also check the shared libraries and client JAR this instance launches from.

          Those live in a store every instance shares, on Maven-style paths rather than under their own digests, so nothing re-checks them once they are written. Their digests come from the release's metadata, which has to have been cached already - launch the instance once if it has not. Only a client instance has them, so this cannot be combined with --server.

  -h, --help
          Print help (see a summary with '-h')

ephervex mod repair​

Replace every file a client or server is missing or holding wrongly.

Checks first, so nothing sound is rewritten, and fetches each replacement before touching anything on disk, so a file that cannot be obtained is left exactly where it is rather than removed.

A file the pack shipped inside itself has no address to go back to, and a server built from published server files records none for its jars. Those are named separately, because trying again does not bring them back: re-import the pack for a client, or put the file back in the server folder by hand.

A mod put aside with `ephervex mod delete` stays aside: a repair only replaces what is missing or wrong, and a deleted mod is neither.

Refused while the host is running or an isolation session is active.

Usage: ephervex mod repair [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

  -h, --help
          Print help (see a summary with '-h')

ephervex mod dependencies​

Show what each mod needs, and what needs it.

Answered from what is recorded here, so it reaches no catalog and works offline. A mod nothing has asked about says so rather than appearing to need nothing; `ephervex mod refresh` is what answers for it.

Relations are shown exactly as the catalog stated them, including the optional and incompatible ones, which no change ever acts on. Only the direct ones: this says what was recorded about a mod, not what a whole cascade would reach.

Usage: ephervex mod dependencies [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --of <PATH>
          One mod's relations instead of every mod's, by its path inside the game directory, such as `mods/foo.jar`

  -h, --help
          Print help (see a summary with '-h')

ephervex mod refresh​

Ask each catalog what a client's or server's mods need, and record the answers.

Ephervex records what a mod requires when it installs it, and when it imports a CurseForge pack. Anything else starts out with nothing recorded: a Modrinth pack states no dependencies at all, and an instance built by an older Ephervex has none. Run this once and the instance can answer what breaks when a mod is turned off, offline and from then on.

A catalog that cannot be reached costs only its own mods' answers. Mods it could not answer for stay unrecorded rather than being recorded as needing nothing. The other catalogs' answers are still recorded, and the command then exits with an error naming the catalogs to retry.

Usage: ephervex mod refresh [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

  -h, --help
          Print help (see a summary with '-h')

ephervex mod isolate​

Narrow a reproducing mod set by testing dependency-safe configurations

Usage: ephervex mod isolate [OPTIONS] <COMMAND>

Commands:
  start   Capture a safety snapshot and apply the first test configuration
  status  Show the durable session without changing its current configuration
  resume  Reapply the current round after a restart or interrupted mutation
  answer  Record whether the current configuration still reproduces the issue
  undo    Remove the latest answer and restore that round for another test
  finish  Keep the smallest tested configuration and retain the safety snapshot
  cancel  Restore the pre-isolation snapshot and end the session
  help    Print this message or the help of the given subcommand(s)

Options:
      --json  Emit machine-readable JSON where the command supports it
  -h, --help  Print help

ephervex mod isolate start​

Capture a safety snapshot and apply the first test configuration

Usage: ephervex mod isolate start [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --keep <PATH>
          Keep this mod and everything it requires enabled in every round

      --accept-unrecorded
          Continue even though refreshable dependency information is absent.

          The final result is marked as reduced confidence because a mod that appears independent may have an unrecorded required dependency.

      --linked-server <SERVER>
          Also keep this linked server's mods in step with each round.

          The server enables a mod exactly when the client round enables the same project, so a bug that needs both sides can be narrowed in one session. It has its own safety snapshot, and until the session ends its mods cannot be changed and it cannot have a session of its own. Start it yourself to test each round. Repeat for several servers.

  -h, --help
          Print help (see a summary with '-h')

ephervex mod isolate status​

Show the durable session without changing its current configuration

Usage: ephervex mod isolate status [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>  The client instance to operate on
      --json                 Emit machine-readable JSON where the command supports it
      --server <SERVER>      The dedicated server to operate on
  -h, --help                 Print help

ephervex mod isolate resume​

Reapply the current round after a restart or interrupted mutation

Usage: ephervex mod isolate resume [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>  The client instance to operate on
      --json                 Emit machine-readable JSON where the command supports it
      --server <SERVER>      The dedicated server to operate on
  -h, --help                 Print help

ephervex mod isolate answer​

Record whether the current configuration still reproduces the issue

Usage: ephervex mod isolate answer [OPTIONS] <--instance <INSTANCE>|--server <SERVER>> <ANSWER>

Arguments:
  <ANSWER>
          Possible values:
          - issue-still-present: The tested configuration still shows the issue
          - issue-gone:          The issue is gone in the tested configuration

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

  -h, --help
          Print help (see a summary with '-h')

ephervex mod isolate undo​

Remove the latest answer and restore that round for another test

Usage: ephervex mod isolate undo [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>  The client instance to operate on
      --json                 Emit machine-readable JSON where the command supports it
      --server <SERVER>      The dedicated server to operate on
  -h, --help                 Print help

ephervex mod isolate finish​

Keep the smallest tested configuration and retain the safety snapshot

Usage: ephervex mod isolate finish [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>  The client instance to operate on
      --json                 Emit machine-readable JSON where the command supports it
      --server <SERVER>      The dedicated server to operate on
  -h, --help                 Print help

ephervex mod isolate cancel​

Restore the pre-isolation snapshot and end the session

Usage: ephervex mod isolate cancel [OPTIONS] <--instance <INSTANCE>|--server <SERVER>>

Options:
      --instance <INSTANCE>  The client instance to operate on
      --json                 Emit machine-readable JSON where the command supports it
      --server <SERVER>      The dedicated server to operate on
  -h, --help                 Print help

ephervex mod delete​

Take a mod's jar off disk, keeping the record that wants it.

Not the same as removing it. The instance still says it should have this mod, so a server built from this recipe still contains it. The jar is put aside and kept, and a repair leaves it aside rather than fetching it again; the desktop application's mod list and Diagnostics put it back. What changes is that the loader cannot see it, which is how a crash gets bisected down to one jar.

A jar placed in the mods folder by hand has no record to keep, so deleting it is permanent.

If other mods need this one, their jars go too, because leaving them installed and unable to load is the state worth avoiding. Ephervex names them and stops, and it also stops for mods that use this one optionally or whose requirements are not recorded, since it cannot tell whether they need it. `--with-dependents` takes the mods that need it as well, and `--only-this` takes just the jar you named.

Usage: ephervex mod delete [OPTIONS] <--instance <INSTANCE>|--server <SERVER>> <PATH>

Arguments:
  <PATH>
          The mod's path inside the game directory, such as `mods/foo.jar`

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --with-dependents
          Also delete every mod that needs this one

      --only-this
          Delete only the jar named, leaving what needs it unable to load

  -h, --help
          Print help (see a summary with '-h')

ephervex mod enable​

Let a mod load again after it was disabled.

A mod that needs others usually cannot load alone. Ephervex says which of them are turned off or not installed, and which installed mods it is declared incompatible with, and stops; `--with-dependencies` turns the ones that are turned off on too, and `--only-this` turns on just the mod you named.

Usage: ephervex mod enable [OPTIONS] <--instance <INSTANCE>|--server <SERVER>> <PATH>

Arguments:
  <PATH>
          The mod's path inside the game directory, such as `mods/foo.jar`

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --with-dependencies
          Also turn on every mod this one needs

      --only-this
          Turn on only the mod named, leaving what it needs turned off

  -h, --help
          Print help (see a summary with '-h')

ephervex mod disable​

Keep a mod installed but stop the loader from loading it.

The jar is renamed to `<name>.jar.disabled`, which every loader ignores. Nothing is deleted and nothing is forgotten: the mod keeps its recorded version and provider, and enabling it again needs no download.

If other mods need this one, they stop loading too. Ephervex names them and stops without changing anything, and it also stops for mods that use this one optionally or whose requirements are not recorded, since it cannot tell whether they need it. `--with-dependents` turns off the mods that need it as well, and `--only-this` turns off just the mod you named, which leaves the others installed but possibly unable to load.

Usage: ephervex mod disable [OPTIONS] <--instance <INSTANCE>|--server <SERVER>> <PATH>

Arguments:
  <PATH>
          The mod's path inside the game directory, such as `mods/foo.jar`

Options:
      --instance <INSTANCE>
          The client instance to operate on

      --json
          Emit machine-readable JSON where the command supports it

      --server <SERVER>
          The dedicated server to operate on

      --with-dependents
          Also turn off every mod that needs this one

      --only-this
          Turn off only the mod named, leaving what needs it unable to load

  -h, --help
          Print help (see a summary with '-h')