/

CLI Installation & Usage

The Shield Java CLI is a standalone command-line tool for obfuscating JAR files without the Gradle plugin. Use it for CI/CD pipelines, backend JVM applications, or any scenario where Gradle integration is not available.

Requirements

  • Java 8 or higher (java -version to check)
  • A ByteHide project token

Installation

Download from Maven Central

Bash
curl -O https://repo1.maven.org/maven2/com/bytehide/shield/shield-java-cli/1.1.5/shield-java-cli-1.1.5.jar

Or download manually from Maven Central.

Verify Installation

Bash
java -jar shield-java-cli-1.1.5.jar --version
# Output: 1.1.5

java -jar shield-java-cli-1.1.5.jar --help

Usage

1. Create a Configuration File

Create shield-config.json:

JSON
{
  "projectToken": "your-bytehide-project-token",
  "inputJars": ["my-app.jar"],
  "outputJar": "my-app-protected.jar",
  "protections": {
    "StringEncryption": true,
    "ConstantMutation": true,
    "DebugInfoRemoval": true,
    "NameObfuscation": true,
    "ControlFlowMatrix": true
  }
}

2. Run

Bash
java -jar shield-java-cli-1.1.5.jar -c shield-config.json

The protected JAR will be written to the path specified in outputJar.

3. Verify

Bash
java -jar my-app-protected.jar

CLI Options

OptionDescription
-c, --config <file>Configuration file (JSON)
-i, --input <file>Input JAR file (overrides config)
-o, --output <file>Output JAR file (overrides config)
-m, --mapping <file>Output mapping file for deobfuscation
-v, --verboseVerbose output
-V, --versionPrint version
-h, --helpShow help

JSON Configuration Reference

Full Example

JSON
{
  "projectToken": "your-token",
  "inputJars": ["app.jar"],
  "outputJar": "app-protected.jar",
  "libraryJars": [],
  "mappingFile": "mapping.txt",

  "protections": {
    "StringEncryption": true,
    "ConstantMutation": true,
    "DebugInfoRemoval": true,
    "NameObfuscation": true,
    "ControlFlowMatrix": true,
    "AntiDebug": false,
    "AntiTamper": false,
    "ReferenceProxy": false,
    "ResourceProtection": false
  },

  "renameMode": "LETTERS",
  "repackageClasses": true,
  "repackageClassesTargetPackage": "a",

  "excludedPackages": [
    "com.example.models",
    "com.example.api:NameObfuscation",
    "com.example.legacy:StringEncryption,ConstantMutation"
  ],

  "keepRules": [
    {
      "classPattern": "com/example/Main",
      "memberPattern": "*",
      "keepNames": true
    }
  ],

  "verbose": true
}

Fields

FieldTypeDefaultDescription
inputJarsString[]requiredInput JAR files to obfuscate
outputJarStringrequiredOutput obfuscated JAR path
libraryJarsString[][]Library JARs (not obfuscated, used for reference resolution)
mappingFileStringnullOutput mapping file for deobfuscation
projectTokenStringrequiredByteHide project token
protectionsObject—Enable/disable individual protections
renameModeString"LETTERS"LETTERS, UNICODE, ASCII, SEQUENTIAL, DECODABLE, FAKE
repackageClassesBooleanfalseFlatten all classes into one package
repackageClassesTargetPackageString"a"Target package name
keepRulesObject[][]ProGuard-compatible keep rules
excludedPackagesString[][]Packages to exclude (global or per-protection)
excludedClassesString[][]Specific classes to exclude
excludedMethodsString[][]Specific methods to exclude
verboseBooleanfalseVerbose output
stringEncryptionModeString"DYNAMIC"DYNAMIC or BASIC
stringEncryptionMinLengthInt3Min string length to encrypt
controlFlowConfig.intensityInt5Control flow intensity (1-10)
controlFlowConfig.depthInt10Control flow depth (1-18)
controlFlowConfig.modeString"MIXED"SWITCH, JUMP, or MIXED
aggressiveOverloadingBooleanfalseReuse names for methods with different signatures
allowAccessModificationBooleanfalseWiden access modifiers
adaptClassStringsBooleanfalseAdapt Class.forName("...") strings when renaming classes

CLI vs Gradle plugin

In the CLI, all JARs listed in inputJars are treated as program classes and obfuscated. Use libraryJars for dependencies that should only be used for reference resolution (not obfuscated). The Gradle plugin handles this separation automatically.

Exclusions

Exclude packages from all protections:

JSON
"excludedPackages": ["com.example.models"]

Exclude packages from specific protections only:

JSON
"excludedPackages": ["com.example.api:NameObfuscation,StringEncryption"]

Keep Rules

Preserve class/member names while still applying other protections:

JSON
"keepRules": [
  {
    "classPattern": "com/example/Main",
    "memberPattern": "*",
    "keepNames": true
  }
]

Use "keepClassName": false to allow class renaming while preserving field/method names (useful for Gson/Jackson DTOs):

JSON
"keepRules": [
  {
    "classPattern": "com/example/dto/**",
    "memberPattern": "*",
    "keepNames": true,
    "keepClassName": false
  }
]

Examples

Obfuscate a Spring Boot JAR

JSON
{
  "projectToken": "your-token",
  "inputJars": ["target/myapp-1.0.0.jar"],
  "outputJar": "target/myapp-1.0.0-protected.jar",
  "protections": {
    "StringEncryption": true,
    "ConstantMutation": true,
    "ControlFlowMatrix": true,
    "DebugInfoRemoval": true
  },
  "excludedPackages": [
    "org.springframework",
    "com.fasterxml.jackson"
  ]
}

Generate a Mapping File

Bash
java -jar shield-java-cli-1.1.5.jar -c shield-config.json -m mapping.txt

The mapping file maps obfuscated names back to original names, useful for reading stack traces from production.

Previous
Gradle Setup
Next
CI/CD Integration