GramAddict Documentation

When you run gramaddict init <account_name>, the following directory structure is created for that account. You should place your configuration and lists in these files:

accounts/
  <youraccountname/
    config.yml
    telegram.yml
    filters.yml
    whitelist.txt
    blacklist.txt
    comments_list.txt
    pm_list.txt

GramAddict avoids the common pitfall of using Instagram's API, which often leads to bans within 1-30 days. Instead, it uses a testing-based approach:

1. ADB & uiautomator2: The bot uses the Android Debug Bridge (ADB) and the uiautomator2 library to control an Android device or emulator.
2. Device-Based Execution: The bot performs actions directly on the device (or emulator) just as a human would, making it significantly more secure and harder for Instagram to detect as a bot.
3. Human Simulation: To prevent bans, the bot must be configured to mimic human patterns (e.g., not scrolling all day, not performing too many actions in a row).

The bot requires an Android device (physical or emulator) running Android 4.4+ with Instagram installed and logged in. Instagram must be set to English.

Physical Device

1. Enable Developer Options and USB Debugging on the phone.
2. Connect the phone to your computer via USB.
3. Accept the connection prompt on the phone.

Emulator (macOS)

1. Install Homebrew and cask.
2. Install Android Studio.
3. Use the Virtual Device Manager in Android Studio to create a device (Pixel 2 API 28 is recommended).
4. Run the device and install/log into Instagram.

Verify Connection

Run adb devices to ensure your device is recognized. You should see a device ID followed by device.

You can install GramAddict using pip (recommended) or by cloning the repository with git.

Important Note: If you install via git, the CLI commands gramaddict init, gramaddict dump, and gramaddict run will not work. You must use the run.py script instead.

It is highly recommended to use a Python virtual environment to avoid dependency conflicts.

# 1. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install via pip (Recommended)
pip3 install GramAddict

# Verify installation
gramaddict --version

# OR: Install via git
git clone https://github.com/GramAddict/bot.git gramaddict
cd gramaddict
pip3 install -r requirements.txt

To run GramAddict, you need a computer (Windows, macOS, Linux, or Raspberry Pi) and an Android device or emulator.

Recommended Setup by OS:

• Windows: Use Memu as an emulator.
• macOS: Android Studio is recommended (can be installed via brew install --cask android-studio).
• Mobile-only: You can run the bot directly on your phone using Termux.

Core Technologies:

• Python 3
• ADB (Android Debug Bridge)
• uiautomator2

Before running the bot, you must initialize the environment and your specific account configuration.

1. Initialize uiautomator2: uiautomator2 init
2. Initialize GramAddict: gramaddict init <your_ig_account_name>
   • This creates an account folder at accounts/<your_ig_account_name>/ containing config.yml, telegram.yml, filters.yml, etc.
   • Note: This command only works if installed via pip. If installed via git, you must create these folders manually.
3. Configure: Edit the generated .yml files in your account folder.
4. Run the bot: Use the --config flag to point to your account's configuration file.

GramAddict requires adb to communicate with your Android device or emulator.

1. Download the Android SDK Platform-Tools.
2. Add the path to the unzipped platform-tools folder to your system's PATH environment variable.
   • Linux/macOS: Add export PATH=/path/to/platform-tools:$PATH to your ~/.bash_profile or equivalent, then restart the terminal.
   • Windows: Add the folder path to your System Environment Variables via the 'Environment Variables' menu in System Properties.
3. Verify the installation by running adb version in your terminal.

The GramAddict CLI supports the following subcommands:

The init command sets up the necessary files to start using GramAddict for a specific Instagram account. It creates a folder under accounts/{account_name} containing configuration templates downloaded from the official repository. It also ensures a run.py file exists in the current working directory.

Note: After running this, you must edit the generated config.yml file according to the GramAddict documentation.

The dump command captures the current state of the connected Android device. It generates a ZIP archive containing a screenshot (screenshot.png) and the UI hierarchy (hierarchy.xml). This is useful for debugging or providing context to developers.

Flags:

• --device: Specify the device name if multiple devices are connected via ADB.
• --no-kill: Prevents the command from killing the atx-agent (uiautomator2 daemon).