Skip to content
SoulFire LogoSoulFire

CLI mode

Run SoulFire from a terminal for automation, SSH, or a server without a desktop.

When to use the CLI

If you are not familiar with command-line tools, start with Connect your first bot.

Use the CLI for terminal automation, SSH sessions, or systems without a desktop. The GUI supports more features, but the CLI covers the most common tasks.

The CLI distribution runs without a desktop or display. Use the separate GUI client when you want the desktop interface.

Set up the CLI

Install Java 25, then download the CLI .jar from the SoulFire releases. The commands below use SoulFireCLI.jar; replace it with your downloaded filename.

Save the JVM flags in a shell variable so that the later commands stay short:

SF_JVM_FLAGS="-Djava.awt.headless=true -Xmx2G -XX:+EnableDynamicAgentLoading -XX:+UnlockExperimentalVMOptions -XX:+UseZGC -XX:+UseCompactObjectHeaders -XX:+AlwaysActAsServerClassMachine -XX:+UseNUMA -XX:+UseFastUnorderedTimeStamps -XX:+UseVectorCmov -XX:+UseCriticalJavaThreadPriority -Dsf.flags.v2=true"

The base command is this:

java $SF_JVM_FLAGS -jar SoulFireCLI.jar

This syntax is for Bash and similar shells. In another shell, put the flags in place of $SF_JVM_FLAGS.

FlagPurpose
-Djava.awt.headless=trueRuns Java without a display
-Xmx2GSets the memory limit for the CLI process
-XX:... flagsPerformance tuning that SoulFire recommends at startup
-Dsf.flags.v2=trueConfirms that you set the tuning flags. It hides the startup warning and does not apply the flags itself.

Change -Xmx2G to fit your workload. For example, -Xmx120G sets a 120 GB limit. If you omit -Xmx, Java uses up to 25% of the total system memory. When the bots run on a remote server, -Xmx1G is usually enough for the local CLI.

Next, choose where the bots will run. For a local server, continue to CLI flags. For a remote dedicated server, set these JVM properties:

PropertyDescription
sf.remoteAddressThe address to connect to
sf.remoteTokenThe token to login with

Put the properties before -jar:

java -Dsf.remoteAddress=domain.com -Dsf.remoteToken=abcdefg $SF_JVM_FLAGS -jar SoulFireCLI.jar

CLI flags

After the CLI connects, it gets the available flags from the server. See CLI flags for the full list.

This example imports accounts and starts the bots:

java $SF_JVM_FLAGS -jar SoulFireCLI.jar \
  --account-file accounts.txt \
  --account-type OFFLINE \
  --bot-address 127.0.0.1:25565 \
  --bot-protocol-version "RELEASE|777" \
  --bot-join-delay-min 1000 \
  --bot-join-delay-max 3000 \
  --start

The command imports the accounts in accounts.txt and connects them to 127.0.0.1:25565. It starts each bot after a random delay of one to three seconds. RELEASE|777 is the ID of Minecraft 26.3. Find other IDs in supported versions. Keep the quotes, because | has a meaning in the shell.

Terminal flags

Set -Dterminal.jline=true or -Dterminal.jline=false to enable or disable the interactive terminal. The interactive terminal uses JLine, the same library used by Minecraft and Velocity. Set -Dterminal.ansi=true or -Dterminal.ansi=false to enable or disable terminal colors.

Importing data

Use CLI flags to import profiles, accounts, and proxies. You must select an account type when you import accounts. The proxy type is optional. SoulFire treats the file as a universal proxy file when you omit the type.

Run commands

The interactive shell accepts the same commands as GUI mode. See the command reference for details.

How is this page?

Last updated on