CLI Mode

When to use the CLI

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.

SoulFire starts in CLI mode when no display is available or when you pass CLI flags to java. You can also set java.awt.headless to true to force CLI mode. The examples on this page use this setting.

Set up the CLI

The SoulFire client distribution includes the CLI. Install Java 25, then download the latest client .jar from the download page.

The base command is this:

java -Djava.awt.headless=true -Xmx$RAM -XX:+EnableDynamicAgentLoading -XX:+UnlockExperimentalVMOptions -XX:+UseZGC -XX:+UseCompactObjectHeaders -XX:+AlwaysActAsServerClassMachine -XX:+UseNUMA -XX:+UseFastUnorderedTimeStamps -XX:+UseVectorCmov -XX:+UseCriticalJavaThreadPriority -Dsf.flags.v2=true -jar SoulFireClient.jar

Replace $RAM with the amount of memory for the CLI process. If you omit -Xmx$RAM, Java uses up to 25% of the total system memory. For example, use -Xmx120G to set a 120 GB limit. 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:

Put the properties before -jar:

java -Dsf.remoteAddress=domain.com -Dsf.remoteToken=abcdefg -Djava.awt.headless=true -Xmx$RAM -XX:+EnableDynamicAgentLoading -XX:+UnlockExperimentalVMOptions -XX:+UseZGC -XX:+UseCompactObjectHeaders -XX:+AlwaysActAsServerClassMachine -XX:+UseNUMA -XX:+UseFastUnorderedTimeStamps -XX:+UseVectorCmov -XX:+UseCriticalJavaThreadPriority -Dsf.flags.v2=true -jar SoulFireClient.jar

CLI flags

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

Here is an example of how to use them:

java -Xmx$RAM -XX:+EnableDynamicAgentLoading -XX:+UnlockExperimentalVMOptions -XX:+UseZGC -XX:+UseCompactObjectHeaders -XX:+AlwaysActAsServerClassMachine -XX:+UseNUMA -XX:+UseFastUnorderedTimeStamps -XX:+UseVectorCmov -XX:+UseCriticalJavaThreadPriority -Dsf.flags.v2=true -jar SoulFireClient.jar --account-file accounts.txt --account-type OFFLINE --bot-address 127.0.0.1:25565 --bot-protocol-version 1.20 --bot-join-delay-min 1000 --bot-join-delay-max 3000 --start

Replace $RAM with the memory limit for the CLI process. This 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.

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 Commands reference for details.