🤖 Insta Meme Bot CLI

A modern, production-ready Instagram meme bot that automatically scrapes memes from Pinterest and posts them to Instagram. Built with Node.js 18+, featuring secure dependencies, CLI interface, and programmatic API support.

✨ Features

• 🎯 Smart Meme Scraping: High-quality memes from Pinterest with modern stealth browsing
• 🤖 Automated Posting: Posts to Instagram with randomized captions and hashtags
• 🛡️ Security First: Modern dependencies, session management, and rate limiting
• 🎭 Multiple Categories: Support for funny, desi, dark humor, trending, and custom memes
• 🖥️ CLI Interface: Easy-to-use command line interface with comprehensive options
• 📦 Programmatic API: Use as a Node.js module in your projects
• 🔄 Flexible Scheduling: Custom intervals from seconds to hours
• 📝 Comprehensive Logging: Detailed logs for monitoring and debugging
• 🔒 Modern Security: Updated dependencies with vulnerability fixes

📋 Requirements

• Node.js: >= 18.0.0 (LTS recommended)
• npm: >= 9.0.0
• Operating System: Linux, macOS, or Windows
• Instagram Account: Valid credentials required

🚀 Installation

Global Installation (Recommended for CLI usage)

npm install -g insta-meme-bot-cli

Local Installation (For programmatic usage)

npm install insta-meme-bot-cli

Verify Installation

insta-meme-bot-cli --version
insta-meme-bot-cli --help

🖥️ CLI Usage

Environment Setup

Create a .env file or set environment variables:

# Option 1: Environment variables
export INSTA_USERNAME="your_instagram_username"
export INSTA_PASSWORD="your_instagram_password"

# Option 2: Create .env file
echo "INSTA_USERNAME=your_username" > .env
echo "INSTA_PASSWORD=your_password" >> .env

Basic Commands

# Test configuration (recommended first step)
insta-meme-bot-cli --test

# Post a single meme and exit
insta-meme-bot-cli --once

# Run continuously with default settings (60min interval)
insta-meme-bot-cli --loop

# Post desi memes every 30 minutes
insta-meme-bot-cli --meme-type desi --interval 30m --loop

# Use custom search query
insta-meme-bot-cli --custom-query "programming memes" --once

# Debug mode (visible browser)
insta-meme-bot-cli --no-headless --once

📚 CLI Options Reference

| Option | Short | Description | Default | |--------|-------|-------------|---------| | --username | -u | Instagram username | INSTA_USERNAME env var | | --password | -p | Instagram password | INSTA_PASSWORD env var | | --meme-type | -t | Meme category (funny, desi, dark, trending, relatable) | funny | | --custom-query | -q | Custom Pinterest search query | - | | --interval | -i | Post interval (30s, 45m, 2h, etc.) | 60m | | --log-file | -l | Log file path | bot.log | | --once | - | Post once and exit | false | | --loop | - | Run continuously | false | | --test | - | Test configuration without posting | false | | --no-headless | - | Run browser in visible mode (debugging) | false | | --help | -h | Show help message | - | | --version | -v | Show version | - |

📦 Programmatic API

Installation for Development

npm install insta-meme-bot-cli

Basic Usage

const { InstagramMemeBot, postMeme, startBot } = require('insta-meme-bot-cli');

// Quick single post
await postMeme({
  username: 'your_username',
  password: 'your_password',
  memeType: 'funny'
});

// Advanced usage with custom configuration
const bot = new InstagramMemeBot({
  username: 'your_username',
  password: 'your_password',
  memeType: 'desi',
  interval: '45m',
  customQuery: 'programming humor'
});

// Post once
await bot.postSingleMeme();

// Start continuous mode
await bot.start();

// Test configuration
const results = await bot.test();
console.log('Test results:', results);

Available Meme Categories

• funny: General funny memes, hilarious content
• desi: Indian/Hinglish memes, Bollywood humor
• dark: Dark humor, sarcastic content
• trending: Viral and trending memes
• relatable: Life, work, student memes

🔧 Configuration

Environment Variables

Create a .env file in your project root:

INSTA_USERNAME=your_instagram_username
INSTA_PASSWORD=your_instagram_password
PUPPETEER_EXECUTABLE_PATH=/path/to/chrome  # Optional: custom Chrome path

Interval Formats

• 30s - 30 seconds
• 45m - 45 minutes
• 2h - 2 hours
• 90m - 90 minutes (use instead of 1h30m)

🛡️ Security & Safety

🔒 ZERO VULNERABILITIES ACHIEVED!

This package has been completely modernized and now has ZERO security vulnerabilities!

Modern Dependencies

• ✅ ZERO vulnerabilities - completely secure package
• ✅ Removed vulnerable instagram-private-api dependency
• ✅ Pure Puppeteer-based Instagram automation
• ✅ Modern @ghostery/adblocker-puppeteer v2.11.6
• ✅ Secure axios HTTP client replacing deprecated request
• ✅ Latest uuid v10 with secure random generation
• ✅ Updated Puppeteer with latest security patches

Built-in Safety Features

• Rate Limiting Protection: Automatic detection and smart backoff
• Session Management: Persistent login sessions with automatic restoration
• Error Handling: Graceful handling of network timeouts and failures
• Stealth Browsing: Anti-detection measures with modern techniques
• Secure Logging: Sensitive data excluded from logs

Instagram ToS Compliance

• Random delays between actions to mimic human behavior
• Respect for Instagram's rate limits
• Session management to reduce login frequency
• Comprehensive error handling for API restrictions

🚀 Getting Started Guide

Step 1: Install

npm install -g insta-meme-bot-cli

Step 2: Setup Credentials

# Create environment file
echo "INSTA_USERNAME=your_username" > .env
echo "INSTA_PASSWORD=your_password" >> .env

Step 3: Test Configuration

insta-meme-bot-cli --test

Step 4: Post Your First Meme

insta-meme-bot-cli --once

Step 5: Run Continuously (Optional)

insta-meme-bot-cli --loop

🐛 Troubleshooting

Common Issues

Command not found after global install:

npm config get prefix
# Add the bin directory to your PATH
export PATH="$(npm config get prefix)/bin:$PATH"

Permission errors on Linux/macOS:

sudo npm install -g insta-meme-bot-cli

Instagram login issues:

• Instagram actively blocks automated browsers - this is expected behavior
• Try running with visible browser: --headless=false --test
• Use a dedicated Instagram account (not your main account)
• Instagram may require phone/email verification for automation
• Verify credentials are correct
• Check if 2FA is enabled (not supported)
• Ensure account is not restricted
• Try running with --test flag first

⚠️ Instagram Anti-Bot Detection Notice: Instagram has sophisticated anti-bot measures that may prevent automated login. This is normal and expected. Consider using the Pinterest scraper independently and manually posting to Instagram if automation is blocked.

Browser launch failures:

# Install dependencies on Ubuntu/Debian
sudo apt-get install -y chromium-browser

# Set custom Chrome path
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

📊 Monitoring & Logs

Log Files

The bot creates detailed logs in bot.log (or custom path):

2024-08-30T10:30:00.000Z - 🚀 Starting Instagram Meme Bot
2024-08-30T10:30:01.000Z - 👤 Logged in as: @your_username (1234 followers)
2024-08-30T10:30:02.000Z - 🔍 Searching for funny memes: "funny memes"
2024-08-30T10:30:15.000Z - ✅ Selected meme: https://i.pinimg.com/originals/...
2024-08-30T10:30:30.000Z - ✅ Post uploaded successfully!

Monitoring Commands

# Watch logs in real-time
tail -f bot.log

# Check bot status (if running in background)
ps aux | grep insta-meme-bot-cli

# Test configuration
insta-meme-bot-cli --test

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Clone the repository
git clone https://github.com/aman179102/Instagram-Automation.git
cd Instagram-Automation

# Install dependencies
npm install

# Run in development mode
npm run debug

# Run tests
npm run test:jest

# Lint code
npm run lint

# Format code
npm run format

Project Structure

insta-meme-bot-cli/
├── src/
│   ├── bot/           # Main bot orchestration logic
│   ├── cli/           # Command line interface
│   ├── instagram/     # Instagram API wrapper
│   ├── scrapers/      # Pinterest scraper with modern adblocker
│   └── utils/         # Utility functions
├── index.js           # Main entry point for programmatic usage
├── package.json       # Package configuration with modern dependencies
└── README.md         # This file

Contribution Guidelines

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with proper tests
4. Follow code style: npm run lint && npm run format
5. Test your changes: npm test
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Submit a pull request

Code Style

• Use modern ES6+ features
• Follow existing code patterns
• Add JSDoc comments for functions
• Include error handling
• Write tests for new features

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 Aman Kumar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙋‍♂️ Support & Contact

• GitHub Issues: Report bugs or request features
• Email: [email protected]
• GitHub: @aman179102

⚠️ Important Disclaimers

Educational Purpose

This tool is created for educational and learning purposes only. It demonstrates:

• Modern Node.js development practices
• Web scraping techniques
• API integration
• CLI tool development
• Security best practices

Instagram Terms of Service

• Using automation tools may violate Instagram's Terms of Service
• Your account may be restricted, shadowbanned, or permanently banned
• Use at your own risk and responsibility
• Always respect platform guidelines and rate limits

Legal Considerations

• Respect copyright laws when posting content
• The bot sources content from Pinterest, but original copyright may still apply
• Always credit original creators when possible
• Consider fair use guidelines in your jurisdiction

Responsible Usage

• Recommended posting frequency: 1-3 posts per day maximum
• Monitor your account for any restrictions or warnings
• Respect rate limits and don't abuse the service
• Use appropriate content that follows community guidelines

⭐ If this project helped you, please give it a star on GitHub!

🔗 Links: GitHub | npm | Issues password: 'your_password', memeType: 'funny' });

// Advanced usage with custom configuration const bot = new InstagramMemeBot({ username: 'your_username', password: 'your_password', memeType: 'desi', interval: '45m', customQuery: 'programming humor' });

// Post once await bot.postSingleMeme();

// Start continuous mode await bot.start();

// Test configuration const results = await bot.test(); console.log('Test results:', results);

## 📖 Detailed Usage

### CLI Options

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--username` | `-u` | Instagram username | `INSTA_USERNAME` env var |
| `--password` | `-p` | Instagram password | `INSTA_PASSWORD` env var |
| `--meme-type` | `-t` | Meme category (funny, desi, dark, trending, relatable) | `funny` |
| `--custom-query` | `-q` | Custom Pinterest search query | - |
| `--interval` | `-i` | Post interval (30s, 45m, 2h, etc.) | `60m` |
| `--log-file` | `-l` | Log file path | `bot.log` |
| `--once` | - | Post once and exit | false |
| `--loop` | - | Run continuously | false |
| `--test` | - | Test configuration without posting | false |
| `--no-headless` | - | Run browser in visible mode (debugging) | false |
| `--help` | `-h` | Show help message | - |
| `--version` | `-v` | Show version | - |

### Environment Variables

Create a `.env` file in your project root:

```env
INSTA_USERNAME=your_instagram_username
INSTA_PASSWORD=your_instagram_password
PUPPETEER_EXECUTABLE_PATH=/path/to/chrome  # Optional: custom Chrome path

Meme Categories

• funny: General funny memes, hilarious content
• desi: Indian/Hinglish memes, Bollywood humor
• dark: Dark humor, sarcastic content
• trending: Viral and trending memes
• relatable: Life, work, student memes

Interval Formats

• 30s - 30 seconds
• 45m - 45 minutes
• 2h - 2 hours
• 1h30m - Not supported, use 90m instead

🛡️ Safety Features

Rate Limiting Protection

• Automatic detection of Instagram rate limits
• Smart backoff strategies (1-3 hours wait time)
• Random delays between actions to mimic human behavior

Session Management

• Persistent login sessions stored locally
• Automatic session restoration on restart
• Clean session handling for checkpoint errors

Error Handling

• Graceful handling of network timeouts
• Retry mechanisms for failed requests
• Comprehensive error logging and recovery

Stealth Browsing

• Puppeteer with stealth plugin
• Random user agents and viewport sizes
• Ad blocker to improve performance
• Anti-detection measures

🔧 Advanced Configuration

Custom Bot Instance

const { InstagramMemeBot } = require('instagram-meme-bot');

const bot = new InstagramMemeBot({
  username: 'your_username',
  password: 'your_password',
  memeType: 'funny',
  interval: '60m',
  customQuery: null,
  sessionPath: './custom-session.json',
  logFile: './custom-bot.log',
  headless: true,
  timeout: 120000
});

// Event handling
bot.on('post_success', (result) => {
  console.log('Post successful:', result);
});

bot.on('error', (error) => {
  console.error('Bot error:', error);
});

Using Individual Components

const { PinterestScraper, InstagramPoster } = require('instagram-meme-bot');

// Pinterest scraper only
const scraper = new PinterestScraper({ headless: false });
const memeUrl = await scraper.scrapeMeme('funny%20memes');

// Instagram poster only
const poster = new InstagramPoster({
  username: 'your_username',
  password: 'your_password'
});
await poster.postImage('./meme.jpg', { memeType: 'funny' });

📊 Monitoring and Logs

Log Files

The bot creates detailed logs in bot.log (or custom path):

2024-01-15T10:30:00.000Z - 🚀 Starting Instagram Meme Bot
2024-01-15T10:30:01.000Z - 👤 Logged in as: @your_username (1234 followers)
2024-01-15T10:30:02.000Z - 🔍 Searching for funny memes: "funny memes"
2024-01-15T10:30:15.000Z - ✅ Selected meme: https://i.pinimg.com/originals/...
2024-01-15T10:30:20.000Z - 📥 Downloading image: https://i.pinimg.com/...
2024-01-15T10:30:25.000Z - 📤 Uploading post to Instagram...
2024-01-15T10:30:30.000Z - ✅ Post uploaded successfully!

Monitoring Commands

# Watch logs in real-time
npm run logs

# Check bot status
ps aux | grep instagram-meme-bot

# Test configuration
npm test

🚨 Important Disclaimers

Instagram Terms of Service

• This tool is for educational purposes only
• Using automation tools may violate Instagram's Terms of Service
• Your account may be restricted, shadowbanned, or permanently banned
• Use at your own risk and responsibility

Legal Considerations

• Respect copyright laws when posting content
• The bot attempts to source from Pinterest, but original copyright may still apply
• Always credit original creators when possible
• Consider fair use guidelines in your jurisdiction

Rate Limiting

• Instagram has strict rate limits for posting
• The bot includes safety measures, but cannot guarantee account safety
• Recommended posting frequency: 1-3 posts per day maximum
• Monitor your account for any restrictions or warnings

🛠️ Development

Local Development

# Clone the repository
git clone https://github.com/yourusername/instagram-meme-bot.git
cd instagram-meme-bot

# Install dependencies
npm install

# Run in development mode
npm run debug

# Run tests
npm run test:jest

# Lint code
npm run lint

# Format code
npm run format

Project Structure

instagram-meme-bot/
├── src/
│   ├── bot/           # Main bot logic
│   ├── cli/           # Command line interface
│   ├── instagram/     # Instagram API wrapper
│   ├── scrapers/      # Pinterest scraper
│   └── utils/         # Utility functions
├── index.js           # Main entry point
├── package.json       # Package configuration
└── README.md         # This file

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests for any improvements.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Linkedin: LINK

⭐ Acknowledgments

• instagram-private-api for Instagram API access
• puppeteer-extra for stealth web scraping
• Pinterest for providing the meme content source

⚠️ Remember: Use this tool responsibly and in compliance with all applicable terms of service and laws. The authors are not responsible for any misuse or consequences of using this software.