Configuration Guide

Learn how to configure CLIcraft and customize your Minecraft instances.

📋 Overview

CLIcraft uses configuration files to manage:

CLI settings (~/.clicraft/settings.json)
Default game settings (~/.clicraft/default-game-settings.json)
Game settings ignore list (~/.clicraft/game-settings-ignore.json)
Authentication data (~/.clicraft/auth/accounts.json)
Aliases for game instances (~/.clicraft/aliases.json)
Instance settings (mcconfig.json)

🏠 Configuration Locations

Global CLI Configuration

CLI-wide settings are stored in your home directory:

~/.clicraft/
├── settings.json              # CLI settings
├── default-game-settings.json # Default Minecraft settings for new instances
├── game-settings-ignore.json  # Game settings to exclude when capturing
└── auth                       # Authentication tokens
    └── accounts.json          # accounts

Instance Configuration

Each instance has its own configuration file:

instance-directory/
└── mcconfig.json

⚙️ CLI Settings (~/.clicraft/settings.json)

Global settings for CLIcraft. Manage with clicraft config.

Structure

{
  checkUpdates: true,
  autoSaveToConfig: true,
  autoLoadConfigOnLaunch: true,
}

Settings Reference

Field	Type	Default	Description
`checkUpdates`	boolean	`true`	automatically check for updates
`autoSaveToConfig`	boolean	`true`	automatically save game settings to mcconfig.json
`autoLoadConfigOnLaunch`	boolean	`true`	automatically load game settings on launch

Managing Settings

# View all settings
clicraft config show

# Change a setting
clicraft config set maxMemory 4G
clicraft config set javaPath /usr/lib/jvm/java-21/bin/java

# Reset to auto-detect
clicraft config set javaPath auto

🚫 Game Settings Ignore List

Controls which Minecraft settings are excluded when capturing game settings. Stored in ~/.clicraft/game-settings-ignore.json.

Default Ignore List

[
  "fullscreen",
  "overrideWidth",
  "overrideHeight",
  "fullscreenResolution",
  "lastServer",
  "resourcePacks",
  "incompatibleResourcePacks",
  "key_*",
  "narrator",
  "highContrast",
  "telemetryOptInExtra",
  "onboardAccessibility"
]

Wildcard Support

Use * as a wildcard suffix to match multiple settings:

key_* - Matches all keybinds (key_attack, key_use, etc.)
soundCategory_* - Matches all sound categories

Managing Ignore List

# View current ignore list
clicraft config ignore

# Add a pattern
clicraft config ignore-add mouseSensitivity
clicraft config ignore-add soundCategory_*

# Remove a pattern
clicraft config ignore-remove key_*

🎮 Default Game Settings

Default Minecraft settings applied to all new instances. Stored in ~/.clicraft/default-game-settings.json.

When you create a new instance with clicraft create, these settings are automatically written to the instance’s options.txt.

Example Configuration

{
  "renderDistance": 16,
  "fov": 80,
  "guiScale": 2,
  "gamma": 0.5,
  "maxFps": 144,
  "lang": "en_us"
}

Managing Default Settings

# View current defaults
clicraft config defaults

# Set a default
clicraft config defaults-set renderDistance 16
clicraft config defaults-set fov 80
clicraft config defaults-set autoJump false

# Remove a default
clicraft config defaults-remove renderDistance

# Clear all defaults
clicraft config defaults-clear

🎮 Instance Configuration (mcconfig.json)

Basic Structure

{
  "configVersion": "0.3.0",
  "name": "my-instance",
  "type": "client",
  "modLoader": "fabric",
  "minecraftVersion": "1.21.11",
  "loaderVersion": "0.18.4",
  "versionId": "fabric-loader-0.18.4-1.21.11",
  "createdAt": "2026-01-19T15:51:05.322Z",
  "mods": [
    {
      "projectId": "AANobbMI",
      "slug": "sodium",
      "name": "Sodium",
      "versionId": "59wygFUQ",
      "versionNumber": "mc1.21.11-0.8.2-fabric",
      "fileName": "sodium-fabric-0.8.2+mc1.21.11.jar",
      "installedAt": "2026-01-19T15:51:06.110Z"
    }
  ],
  "gameSettings": {
    "renderDistance": 12,
    "fov": 70,
    "guiScale": 2,
    "gamma": 0.5
  }
}

Configuration Fields

Field	Type	Description	Example
`configVersion`	string	CLIcraft version that created this config	`"0.3.0"`
`name`	string	Instance name	`"modded-survival"`
`type`	string	Instance type	`"client"` or `"server"`
`modLoader`	string	Mod loader type	`"fabric"` or `"forge"`
`minecraftVersion`	string	Minecraft version	`"1.21.11"`
`loaderVersion`	string	Loader version	`"0.18.4"`
`versionId`	string	Full version identifier	`"fabric-loader-0.18.4-1.21.11"`
`createdAt`	string	ISO timestamp of creation	`"2026-01-19T15:51:05.322Z"`
`mods`	array	List of installed mods	See below
`gameSettings`	object	Minecraft game settings	See below

Mods Array

Each mod entry contains:

Field	Type	Description
`projectId`	string	Modrinth project ID
`slug`	string	Modrinth project slug
`name`	string	Display name
`versionId`	string	Modrinth version ID
`versionNumber`	string	Version string
`fileName`	string	JAR filename
`installedAt`	string	Installation timestamp
`updatedAt`	string	Last update timestamp (if updated)

Game Settings

The gameSettings object stores Minecraft options that will be applied when creating an instance from this config. These correspond to entries in Minecraft’s options.txt.

# Capture current game settings to mcconfig.json
clicraft config capture

# View saved game settings
clicraft config game-settings

# Clear saved game settings
clicraft config clear-game-settings

Common settings you might want to share:

renderDistance - View distance (2-32)
fov - Field of view (30-110)
guiScale - GUI scale (0=auto, 1-4)
gamma - Brightness (0.0-1.0)
maxFps - Frame rate limit
lang - Language code (e.g., “en_us”)

🔄 Creating from Config

When you run clicraft create in a directory containing mcconfig.json, CLIcraft will:

Detect the existing configuration
Show the config details for confirmation
Prompt for a new instance name
Create the instance with the same settings
Install all mods from the config
Apply game settings (if present)

🔐 Authentication Configuration

Storage Location

~/.clicraft/auth.json

Structure (DO NOT EDIT MANUALLY)

{
  "accessToken": "eyJ...",
  "refreshToken": "M.R3...",
  "expiresAt": 1705420800000,
  "profile": {
    "username": "Player123",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Security Notes

Never share this file - it contains your account credentials
Keep it private - set appropriate file permissions
Automatic management - CLIcraft handles this file automatically
Token refresh - CLIcraft refreshes tokens automatically

File Permissions

On Linux/macOS, secure your auth file:

chmod 600 ~/.clicraft/auth.json

📁 Directory Structure

Complete Instance Layout

my-instance/
├── mcconfig.json          # Instance configuration (THIS FILE)
├── launch.sh              # Generated launch script (reference)
├── assets/                # Game assets
│   ├── indexes/           # Asset indexes
│   ├── objects/           # Asset files
│   └── skins/             # Player skins cache
├── libraries/             # Java libraries
│   ├── com/               # Maven-style structure
│   ├── net/
│   └── ...
├── mods/                  # Installed mods
│   ├── sodium-*.jar
│   ├── lithium-*.jar
│   └── ...
├── natives/               # Platform-specific libraries
│   ├── liblwjgl.so        # Linux
│   ├── liblwjgl.dylib     # macOS
│   └── lwjgl.dll          # Windows
├── versions/              # Version JARs and metadata
│   ├── 1.21.1.jar
│   ├── 1.21.1.json
│   └── fabric-loader-*.jar
├── saves/                 # World saves
│   ├── New World/
│   └── Creative Testing/
├── resourcepacks/         # Resource packs
├── shaderpacks/           # Shader packs (if using shaders)
├── config/                # Mod configuration files
├── logs/                  # Game logs
│   ├── latest.log
│   └── 2024-01-15-1.log.gz
├── crash-reports/         # Crash reports (if crashes occur)
├── screenshots/           # In-game screenshots
└── options.txt            # Game settings

🔍 Troubleshooting

Invalid JSON

If you get JSON errors:

# Validate JSON
cat mcconfig.json | python -m json.tool

Wrong Java Version

Verify Java path:

java --version
which java

Update javaPath in config.

Memory Errors

If game crashes with memory errors:

Reduce -Xmx value
Close other applications
Check available system RAM

← Back to Home