How to Use Holehe CLI Arguments for OSINT Email Investigations

Holehe parses command-line arguments through Python's argparse module in holehe/core.py, allowing users to specify a target email and optional flags such as --only-used, --csv, and --timeout to customize output filtering, export formats, and HTTP request behavior.

Holehe is a popular open-source OSINT tool maintained by megadose that verifies email address usage across hundreds of platforms. The tool's functionality is exposed through a comprehensive command-line interface defined in holehe/core.py, where the maincore() coroutine orchestrates module loading, asynchronous execution, and result formatting. Mastering the available CLI arguments enables investigators to optimize performance, filter noise, and export results for digital reconnaissance workflows.

CLI Architecture and Entry Point

The Holehe CLI is registered as a console script in setup.py via the entry point holehe = holehe.core:main. When you execute the holehe command, Python invokes the maincore() asynchronous function located in holehe/core.py.

Inside maincore(), the ArgumentParser is instantiated between lines 80 and 97. The parser uses Python's standard argparse module to define positional and optional arguments, converting raw command-line input into a structured namespace object called args. This namespace drives all subsequent execution decisions, from email validation to module selection and output formatting.

Complete Holehe CLI Arguments Reference

Holehe accepts one positional argument and multiple optional flags that modify its reconnaissance behavior.

Target Email (Positional)

The email argument is the only required parameter. Holehe validates this input using the is_email() function before processing. Only the first email address is processed; additional positional arguments are ignored by the parser.

holehe user@example.com

Output Filtering

--only-used filters results to display only sites where the email was found (marked with [+]). When enabled, this flag modifies the print_result() function to suppress errors, rate-limit notifications, and "not used" entries, providing a cleaner output focused on confirmed hits.

Display Control

--no-color disables ANSI color codes in terminal output. This flag alters the behavior of print_color() to return plain text, which is essential when piping output to log files or processing results in non-ANSI terminals.

--no-clear prevents the terminal screen from being cleared before results display. By default, Holehe sends the "\033[H\033[J" escape sequence to clear the screen; this flag skips that operation in print_result().

Module Execution

-NP or --no-password-recovery skips password-recovery attempts on sites that expose recovery email addresses. When this flag is set, the get_functions() method filters out modules tagged for password-recovery checks, reducing noise and execution time.

Data Export

-C or --csv exports the complete JSON-like result set to a timestamped CSV file. This triggers the export_csv() function after console output, creating a persistent record of all checked sites regardless of the --only-used filter.

Performance Tuning

-T or --timeout specifies the maximum HTTP request timeout in seconds for each site check. The default value is 10 seconds. This parameter is passed directly to httpx.AsyncClient(timeout=...) to control network resilience on slow connections.

Practical Usage Examples

Execute a basic scan against a single email address:

holehe test@example.com

Display only confirmed hits where the email exists:

holehe test@example.com --only-used

Run a scan suitable for logging or piping to other tools:

holehe test@example.com --no-color --no-clear

Skip password-recovery modules for faster execution:

holehe test@example.com --no-password-recovery

Increase timeout for unreliable network conditions and export to CSV:

holehe test@example.com --timeout 30 --csv

Combine multiple options for a production OSINT workflow:

holehe test@example.com --only-used --no-color --csv --timeout 20

How CLI Arguments Control Execution

After parser.parse_args() executes in maincore(), the resulting args namespace drives the application logic through several distinct phases.

First, the is_email() function validates the positional email argument. Invalid inputs terminate execution before network requests begin.

Second, import_submodules() dynamically loads every module under holehe/modules/. The get_functions() method then filters these modules based on the --no-password-recovery flag, excluding recovery-specific checks when requested.

Third, Holehe initializes a Trio nursery to execute launch_module() for each remaining check concurrently. The --timeout value configures the httpx.AsyncClient instance used across all modules.

Finally, print_result() renders the output according to --only-used, --no-color, and --no-clear directives. If --csv is specified, export_csv() writes the complete dataset to disk regardless of console filtering.

Summary

• The Holehe CLI is defined in holehe/core.py with the argument parser configured at lines 80-97.
• One positional argument (email) is required; all other flags are optional.
• Use --only-used to filter output to confirmed hits only.
• Export results with --csv while controlling display formatting via --no-color and --no-clear.
• Adjust network performance using --timeout and reduce module scope with --no-password-recovery.
• The entry point holehe.core:main registered in setup.py launches the maincore() coroutine.

Frequently Asked Questions

How do I check multiple email addresses with Holehe?

Holehe's CLI parser in holehe/core.py processes only the first positional argument as the target email. Additional arguments are ignored by the ArgumentParser. To check multiple addresses, invoke the tool separately for each email or script multiple executions in a shell loop.

Where does Holehe store CSV exports when using the --csv flag?

When you specify --csv or -C, Holehe calls export_csv() to generate a timestamped CSV file in the current working directory. The filename includes a datetime stamp to prevent overwrites. The file contains all checked sites and their status codes, regardless of the --only-used console filter.

Why does Holehe clear my terminal screen by default?

The default behavior in print_result() sends ANSI escape sequences (\033[H\033[J) to clear the screen before displaying results, providing a clean presentation. Use the --no-clear flag to disable this behavior when you need to preserve previous terminal output or when running in environments that do not support ANSI codes.

How can I speed up Holehe scans on slow networks?

Increase the --timeout value above the default 10 seconds if you encounter frequent timeouts, or decrease it for faster failure on unresponsive sites. Additionally, use --no-password-recovery to skip modules that perform recovery checks, reducing the total number of HTTP requests executed by the Trio nursery.

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