https://github.com/telecter/cmd-launcher
A minimal command line Minecraft launcher + API with in-built support for mod loaders.
https://github.com/telecter/cmd-launcher
cli go minecraft minecraft-launcher
Last synced: 5 months ago
JSON representation
A minimal command line Minecraft launcher + API with in-built support for mod loaders.
- Host: GitHub
- URL: https://github.com/telecter/cmd-launcher
- Owner: telecter
- License: mit
- Created: 2024-03-14T21:17:39.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-15T21:29:27.000Z (5 months ago)
- Last Synced: 2026-01-16T00:13:09.443Z (5 months ago)
- Topics: cli, go, minecraft, minecraft-launcher
- Language: Go
- Homepage:
- Size: 53 MB
- Stars: 19
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# cmd-launcher
A minimal command line Minecraft launcher.
EN | [DE](README_de.md)
[](https://github.com/telecter/cmd-launcher/actions/workflows/build.yml)
[](https://pkg.go.dev/github.com/telecter/cmd-launcher)
- [Installation](#installation)
- [Building from source](#building-from-source)
- [Usage](#usage)
- [Creating an instance](#creating-an-instance)
- [Starting the game](#starting-the-game)
- [Authentication](#authentication)
- [Instance Configuration](#instance-configuration)
- [Search](#search)
[API Documentation](docs/API.md)
## Installation
### Binaries
You can download prebuilt binaries from the Releases tab here on GitHub.
Builds of the latest commit are available at [nightly.link](https://nightly.link/telecter/cmd-launcher/workflows/build/main).
### Via go install
Make sure you have [Go](https://go.dev) installed.
**To install the latest version, run:**
```bash
go install github.com/telecter/cmd-launcher@latest
```
Replace `latest` with `main` for the latest commit.
### Building from source
1. Clone the repository: `git clone https://github.com/telecter/cmd-launcher`
2. In the source directory, run `go run .` to compile and run the launcher.
3. Once you are ready, compile the executable with `go build .`
## Usage
Use the `--help` flag to get the usage information of any command.
### Instances
**Creating an instance**
To create a new instance, use the `inst create` command.
You can use the `--loader, -l` flag to set the mod loader. Forge, NeoForge, Fabric, and Quilt are all supported. If you want to select a specific version of the loader, use the `--loader-version` flag. Otherwise, the latest applicable version is chosen.
Use the `--version, -v` flag to set the game version. If no value is supplied, the latest release is used. Acceptable values also include `release` or `snapshot` for the latest of either.
When starting the game, the launcher will attempt to download a Java runtime from Mojang. If it can't find a suitable one, you will need to set one manually in the instance configuration.
```sh
cmd-launcher inst create -v 1.21.8 -l fabric CoolInstance
```
**Deleting instances**
If you want to delete an instance, use the `inst delete` command followed by the instance name.
### Starting the Game
> [!IMPORTANT]
> This launcher has not been tested for versions < 1.14. It may not work, but I am working on fixing these issues.
To start Minecraft, simply run the `start` command followed by the name of the instance you want to start.
```bash
cmd-launcher start CoolInstance
```
To set game options and override instance configuration, you can set specific flags on the `start` command. These can be viewed in the help text.
**Verbosity**
To increase the verbosity of the launcher, use the `--verbosity` flag. It can be set to either:
- `info` - default, no extra logging
- `extra` - more information when starting the game
- `debug` - debug information useful for debugging the launcher
### Authentication
If you want to play the game in online mode, you will need to add a Microsoft account.
To do this, use the `auth login` command. As part of Microsoft's OAuth2 flow, the default web browser will be opened to complete the authentication. This can be avoided with the `--no-browser` flag.
The launcher will automatically attempt to start the game in online mode if there is an account present.
To play in offline mode, just pass the `-u, --username ` flag to the `start` command
to set your username and the game will automatically launch in offline mode.
You can log out via the `auth logout` command.
### Instance Configuration
To change configuration values for an instance, navigate to the instance directory and open the `instance.toml` file.
Configurable values are:
- Game version
- Mod loader and version (if not vanilla)
- Window resolution
- Java executable path (if empty, a Mojang-provided Java runtime will be downloaded)
- Custom JAR path to use instead of downloading the normal client JAR
- Extra Java args
- Minimum and maximum memory
As mentioned previously, these values can be overriden with command line flags.
**Example `instance.toml` file**
```toml
game_version = '1.21.8'
mod_loader = 'fabric'
mod_loader_version = '0.16.14'
[config]
# Path to a Java executable. If blank, a Mojang-provided JVM will be downloaded.
java = '/usr/bin/java'
# Extra arguments to pass to the JVM
java_args = ''
# Path to a custom JAR to use instead of the normal Minecraft client
custom_jar = ''
# Minimum game memory, in MB
min_memory = 512
# Maximum game memory, in MB
max_memory = 4096
# Game window resolution
[config.resolution]
width = 1708
height = 960
```
### Search
The `search` command can search for Minecraft or mod loader versions. It defaults to searching for game versions, but can also be used to search for Fabric, Quilt, and Forge versions.
```bash
cmd-launcher search [] [--kind {versions, fabric, quilt, forge}]
```