hopper/README.md

```
              ___---___
        ___---    |    ---___
     ---      ___---___      ---
    |---___---         ---___---|
    |      ---___   ___---      |
     ---___       |       ___---
           |---___|___---|
            --__  -  __--
                |-_-|
                 -_-
    __  __
   / / / /___  ____  ____  ___  _____
  / /_/ / __ \/ __ \/ __ \/ _ \/ ___/
 / __  / /_/ / /_/ / /_/ /  __/ /
/_/ /_/\____/ .___/ .___/\___/_/
           /_/   /_/
```

# Hopper

A Minecraft package manager for the terminal.

Hopper can automatically search, download, and update Minecraft mods, modpacks,
resource packs, and plugins from [Modrinth](https://modrinth.com/) so that
keeping your mods up-to-date and compatible with each other is easy. With
Hopper, you won't have to manually visit [CurseForge](https://curseforge.com/)
and download each mod one by one every time you set up a new instance or deal
with the hassle of swapping out different mod versions for hours while trying to
get Minecraft to accept them all at once.

Hopper is still very early in development, but important features are coming
along smoothly, and we'll have lots of progress to show off in the coming weeks.
It’s written in [Rust](https://www.rust-lang.org/) and released under the
[GNU AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html).

We’re looking for people to help contribute code and write documentation. Please
reach out to us in [our Discord “server”](https://discord.gg/jJutHQjsh9) if
you’re interested in helping out. If you have a taste in CLI apps like Hopper,
your input is especially appreciated.

Inspired by applications like [paru](https://github.com/morganamilo/paru), a
feature-packed AUR helper and [topgrade](https://github.com/r-darwish/topgrade),
a tool to upgrade everything.

[![Donate using
Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/tebibytemedia/donate)

## High-level Goals

### Continuous
- Small binary size
- Minimal compile times

### Features

High Priority:
- Modrinth package searching
- Modrinth package installation
- Parallel package downloading
- Per-instance package management
- Package updating
- Listing installed packages

Medium Priority
- CurseForge package searching
- CurseForge package installation
- A `man(1)` entry

Low Priority:
- Shell autocomplete
- Configurable search result display like [Starship](https://starship.rs)
- Version-control system repository package management & compilation

External-Dependent:
- Conflict resolution
- Dependency resolution
- Integration into [Prism Launcher](https://prismlauncher.org/) and/or
[theseus](https://github.com/modrinth/theseus)
- Integration into `topgrade(1)`
- Graphical frontend with notifications

[Modrinth REST API
documentation](https://docs.modrinth.com/api-spec/)

# File Structure

```
├── "$XDG_CONFIG_HOME"/hopper.toml
├── "$XDG_DATA_HOME"/hopper/
│   ├── 1.19.1/
│   │ └── fabric/
│   └── 1.18.2/
│     ├── forge/
│     └── plugin/
└── "$XDG_DATA_HOME"/templates/
      └── example-template.hop -> ~/.minecraft/mods/example-template.hop
```

# Hopfile Structure

Hopfiles will contain a Minecraft version number, a list of packages, and any 
references to other hopfiles on which it’s based, or “templates”. If a hopfile
is based on other template hopfiles, it inherits the packages from them. A
hopfile does not inherit the package or Minecraft version from a template.

```
template = "example-template"
mc-version = "1.19.2"

[packages]
fabric-mod = [ "sodium", "lithium" ]
resource = "alacrity"
```

# Hopper Configuration File Structure

Hopper’s configuration will be maintained with a list of all hopfiles known to
hopper. Its config file will also contain a list of mod hosting sites like
Modrinth and CurseForge and a list of (remote or local) version-control
repositories from which to compile mods. The latter will use a (potentially
custom) build file format to be defined at a later date.

```
hopfiles = [
  "~/.minecraft/mods/template.hop",
  "~/.minecraft/1.91.1/mods/1.19.1.hop" 
]

[sources]
modrinth = "https://api.modrinth.com/"
curseforge = "https://api.curseforge.com/"
git = [
  "git+https://github.com/IrisShaders/Iris.git"
  "git+https://github.com/CaffeineMC/sodium-fabric.git"
]
```

## Documentation

### Types

There are multiple types of packages hopper can manage.

#### Mods
- `fabric-mod`
- `forge-mod`
- `quilt-mod`

#### Modpacks
- `fabric-pack`
- `forge-pack`
- `quilt-pack`

#### Plugins
- `bukkit-plugin`
- `paper-plugin`
- `purpur-plugin`
- `spigot-plugin`
- `sponge-plugin`

#### Other
- `data-pack` (planned)
- `resource-pack`

These types are specified in various hopper subcommands and in its
configuration.

### Usage

`hopper [options...] [subcommand...]`

### Options

`-v`, `--verbose`

 Includes debug information in the output of `hopper` subcommands.

## Subcommands

### `add [options...] [packages...]`

 Adds packages to the current hopfile, symlinking them to its directory. If
the package cannot be found in the package cache, `hopper get` is run first.

OPTIONS

  `-f`, `--hopfile [hopfiles...]`

  Specifies hopfiles to which mods will be added.

 `-m`, `--mc-version [version...]`

  Overrides the version of Minecraft added packages will be for.

### `get [options...] [targets...]`

 Searches for packages, displays the results, and downloads any selected
packages to the local cache. If multiple targets are specified, results are
displayed in order of specification.

OPTIONS

 `-d`, `--dir [directory...]`

  Specifies the directory to download to (default is
`"$XDG_DATA_HOME"/hopper/`).

 `-m`, `--mc-version [version...]`

  Specifies for what version of Minecraft packages are being
retrieved.

 `-n`, `--no-confirm`

  Does not display search results and downloads exact matches to the
cache. Requires `--mc-version` and `--type` be specified.

 `-t`, `--type [types...]`

  Specifies what types of packages are being queried.

### `init [options...]`

 Creates a hopfile in the current directory and adds it to the global known
hopfiles list.

OPTIONS

 `-d`, `--dir [directory...]`

  Specifies the directory in which the hopfile is being created.

 `-f`, `--hopfile [hopfiles...]`

  Specifies templates upon which to base the new hopfile.

 `-m`, `--mc-version [version...]`

  Specifies the version of Minecraft packages are being managed for.

 `-t`, `--type [type...]`

  Specifies what type of packages will be listed in this hopfile.


### `list [options...]`

 Lists all installed packages.

OPTIONS

  `-f` `--hopfile [hopfiles...]`

  Lists packages installed in a specified hopfile.

 `-m`, `--mc-version [version...]`

  Specifies for what version of Minecraft packages are being managed.

 `-t`, `--type [types...]`

  List all packages of a specified type.

### `remove [options...] [packages...]`

 Uninstalls packages.

OPTIONS

 `-f`, `--hopfile [hopfiles...]`

  Removes only packages in the specified hopfile.

 `-m`, `--mc-version [version]`

  Specifies the version of Minecraft the packages are being
uninstalled for.

 `-t`, `--type [types...] [packages...]`

  Removes only packages of a specified type. Optionally takes a list
of packages as an argument.

### `update [options...]`

 Updates installed packages. This command also adds mods to directories
with known hopfiles if the hopfile lists a mod which is not present.

OPTIONS

 `-f`, `--hopfile [hopfiles...]`

  Updates only packages in the specified hopfile.

 `-m`, `--mc-version [version...]`

  Specifies the version of Minecraft packages are being updated for.

 `-t`, `--type [types...] [packages...]`

  Updates only packages of a specified type. Optionally takes a list
of packages as an argument.