/

Install via CLI (pip)

Install Shield iOS via pip. Works on macOS and Linux.

Requirements

  • Python 3.9 or later
  • macOS (recommended) or Linux
  • Active ByteHide subscription

Install

Bash
pip install bytehide-shield-ios

Verify the installation:

Bash
shield-ios version

Quick Start

1. Initialize configuration

Bash
shield-ios init

This creates a shield-ios.json file in the current directory.

2. Add your project token

Edit shield-ios.json and add your ByteHide project token:

JSON
{
  "projectToken": "bh_YOUR_PROJECT_TOKEN_HERE",
  "protections": {
    "anti_debug": true,
    "string_encryption": true,
    "control_flow": "medium"
  }
}

Get your token from the ByteHide dashboard.

3. Protect your app

Bash
# Protect an IPA
shield-ios protect MyApp.ipa --config shield-ios.json

# Protect an xcarchive
shield-ios protect MyApp.xcarchive --config shield-ios.json --no-sign

Output: MyApp_protected.ipa

CLI Reference

CODE
shield-ios protect <input> [options]
shield-ios init
shield-ios version

Options

OptionDescription
--config <path>Path to configuration file
--output <path>Custom output path
--no-signSkip code signing
--verboseVerbose output

Input Formats

Shield iOS supports two input formats:

FormatDescriptionWhen to Use
.ipaStandard iOS application archiveDirect IPA protection and re-signing
.xcarchiveXcode Archive (from Product > Archive)Post-archive protection with --no-sign (Xcode handles signing during distribution)

Examples

Bash
# Protect an IPA
shield-ios protect MyApp.ipa --config shield-ios.json

# Protect an xcarchive (in-place, no re-signing)
shield-ios protect MyApp.xcarchive -o MyApp.xcarchive --config shield-ios.json --no-sign

# Custom output path
shield-ios protect MyApp.ipa --output builds/MyApp_secure.ipa --config shield-ios.json

# Verbose mode
shield-ios protect MyApp.ipa --config shield-ios.json --verbose

Configuration Examples

Minimal (development)

JSON
{
  "projectToken": "bh_YOUR_TOKEN",
  "protections": {
    "anti_debug": true,
    "string_encryption": true
  }
}
JSON
{
  "projectToken": "bh_YOUR_TOKEN",
  "protections": {
    "anti_debug": true,
    "anti_jailbreak": true,
    "string_encryption": true,
    "symbol_renaming": true,
    "control_flow": "medium",
    "opaque_predicates": "medium"
  }
}

Maximum (high-security)

JSON
{
  "projectToken": "bh_YOUR_TOKEN",
  "protections": {
    "anti_debug": true,
    "anti_jailbreak": {
      "enabled": true,
      "sensitivity": 2,
      "exit_on_detect": true
    },
    "string_encryption": true,
    "symbol_renaming": true,
    "swift_stripping": true,
    "control_flow": "aggressive",
    "dead_code_injection": "heavy",
    "opaque_predicates": "complex",
    "class_encryption": true,
    "resource_encryption": true,
    "rasp": {
      "enabled": true,
      "hook_detection": true,
      "trace_detection": true,
      "tamper_detection": true,
      "action": "exit"
    }
  }
}

Code Signing

Shield can re-sign your app after protection:

JSON
{
  "code_signing": {
    "identity": "Apple Development",
    "provisioning_profile": "/path/to/profile.mobileprovision",
    "skip_if_not_macos": true
  }
}

Or skip signing with --no-sign and let Xcode/Fastlane handle it.

Updating

Bash
pip install --upgrade bytehide-shield-ios

Virtual Environments

For isolated installations:

Bash
python3 -m venv shield-env
source shield-env/bin/activate
pip install bytehide-shield-ios

Troubleshooting

"shield-ios: command not found"

The pip scripts directory is not in your PATH. Try:

Bash
python -m shield_ios.shield protect MyApp.ipa --config shield-ios.json

Or add the pip bin directory to your PATH:

Bash
export PATH="$HOME/.local/bin:$PATH"

"No project token configured"

Add a valid projectToken to your shield-ios.json. Get one from cloud.bytehide.com/product/shield.

"Cloud validation failed"

Your token may be invalid or expired. Check your ByteHide dashboard.

Next Steps

Xcode Integration

Protect automatically on Archive

Configuration Reference

Full configuration options

Homebrew Installation

Install via Homebrew on macOS

Previous
Automatic Setup
Next
Homebrew