How to Use Holehe from the Command Line to Check an Email

You can check if an email address is registered across 120+ online services by running holehe test@example.com in your terminal, which executes an asynchronous OSINT engine that queries each platform concurrently and returns a standardized results table.

Holehe is a Python-based open-source intelligence (OSINT) tool maintained by megadose/holehe that checks email address usage across social media, shopping, and service platforms. The command-line interface provides a straightforward entry point to the tool's asynchronous checking engine without requiring any Python scripting knowledge. When you use Holehe from the command line to check an email, you trigger a sophisticated workflow involving dynamic module loading, concurrent HTTP requests, and structured result aggregation.

Installation and CLI Entry Point

The holehe command becomes available after installation via the console-script entry point defined in setup.py.

entry_points={
    'console_scripts': [
        'holehe = holehe.core:main',
    ],
}

When invoked, this entry point executes the main() function located in holehe/core.py, which immediately delegates to the asynchronous maincore() coroutine to handle the actual execution flow.

Basic Command Line Syntax

The simplest usage requires only the target email address as a positional argument:

holehe test@example.com

Holehe first validates the supplied string using the is_email() utility; if validation fails, the program aborts immediately with an error message. Valid emails proceed through the full checking pipeline against all available service modules.

Core Execution Workflow

The CLI orchestrates six distinct phases when processing an email check, all managed within holehe/core.py.

Argument Parsing

The ArgumentParser collects configuration options that modify execution behavior and output formatting:

parser.add_argument("email", help="Email to check")
parser.add_argument("--csv", action="store_true", help="Export results to CSV")
parser.add_argument("--no-color", action="store_true", help="Disable colored output")
parser.add_argument("--only-used", action="store_true", help="Show only services where email is used")
parser.add_argument("-t", "--timeout", type=int, default=10, help="Timeout in seconds")

These flags allow you to tailor the scan to your specific OSINT requirements without modifying any code.

Dynamic Module Loading

Holehe discovers service-specific checkers by dynamically importing all modules located under holehe/modules/ using import_submodules("holehe.modules"). Each module exports an async function implementing platform-specific logic—typically querying password-recovery endpoints or registration APIs to infer account existence.

Concurrent OSINT Checks

The tool maximizes performance by executing all service checks concurrently using the Trio async library. The maincore() function creates an httpx.AsyncClient instance and launches each module as a separate task within a Trio nursery:

async with trio.open_nursery() as nursery:
    for module in modules:
        nursery.start_soon(launch_module, module, email, client, out)

This architecture respects the user-defined timeout (default 10 seconds) while querying over 120 services simultaneously.

Results and Output

Each service module returns a standardized dictionary with the following schema:

• name: Service identifier
• domain: Service domain
• rateLimit: Boolean indicating if the check was rate-limited
• exists: Boolean indicating if the email is registered
• emailrecovery: Recovery email hint if available
• phoneNumber: Partial phone number if exposed
• others: Additional metadata

The print_result() function aggregates these dictionaries, sorts them alphabetically, and displays them in a formatted table. If you specify the --csv flag, export_csv() writes timestamped results to a file and exits without printing to stdout.

Practical CLI Examples

Run a comprehensive check against all supported services:

holehe target@example.com

Filter results to show only confirmed accounts while suppressing ANSI color codes:

holehe target@example.com --only-used --no-color

Export findings for further analysis in a spreadsheet:

holehe target@example.com --csv

For programmatic integration within Python scripts, you can bypass the CLI and call individual modules directly using the same async infrastructure:

import trio
import httpx
from holehe.modules.social_media.snapchat import snapchat

async def check_email():
    email = "target@example.com"
    results = []
    async with httpx.AsyncClient() as client:
        await snapchat(email, client, results)
    print(results)

trio.run(check_email)

Summary

• Entry Point: The holehe command maps to holehe.core:main in setup.py, launching the async engine in holehe/core.py.
• Validation: All input emails pass through is_email() before processing begins.
• Modularity: Service checks are dynamically loaded from holehe/modules/ via import_submodules().
• Concurrency: Trio nurseries and httpx.AsyncClient enable simultaneous querying of 120+ services.
• Output: Results follow a standardized schema supporting terminal display (print_result()) or CSV export (export_csv()).
• Flexibility: CLI flags (--only-used, --no-color, --csv) allow customization without code changes.

Frequently Asked Questions

How do I install Holehe to use it from the command line?

Install Holehe via pip from the megadose/holehe repository: pip install holehe. This creates the holehe executable in your PATH through the setuptools entry point defined in setup.py, allowing immediate terminal usage without manual script execution.

What information does Holehe return when checking an email?

According to the source code in holehe/core.py, each service returns a dictionary containing name, domain, rateLimit, exists, emailrecovery, phoneNumber, and others. The exists field indicates whether the email is registered, while emailrecovery and phoneNumber may contain partial credentials leaked by password-reset endpoints.

Can I run Holehe without the command line interface?

Yes. You can import individual service modules from holehe/modules/ and call their async functions directly with an httpx.AsyncClient instance. This bypasses the CLI argument parsing in holehe/core.py while utilizing the same concurrent checking logic implemented in the core engine.

How does Holehe check so many services simultaneously?

The tool uses Trio, a Python async library, to run checks concurrently. The maincore() function opens a Trio nursery and calls nursery.start_soon() for each service module, allowing all 120+ checks to execute in parallel while sharing a single HTTP client session with configurable timeout limits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}