# How to Run Holehe from the Command Line: Installation, Usage, and Options

> Learn to run Holehe from the command line for OSINT email investigations. Install via pip and use simple commands with optional flags for data export and filtering.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: how-to-guide
- Published: 2026-08-26

---

**Holehe installs as a pip package with a console script entry point at `holehe.core:main`, enabling you to execute OSINT email investigations by typing `holehe user@example.com` followed by optional flags to filter results, disable colors, or export data to CSV.**

Holehe is an open-source OSINT (Open Source Intelligence) tool maintained in the `megadose/holehe` repository that checks email addresses against over 120 online services. Designed specifically for command-line workflows, Holehe exposes a terminal interface that parses arguments via `argparse` and orchestrates asynchronous checks using `trio`. Understanding how to run Holehe from the command line requires familiarity with its entry point configuration in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) and the core execution logic defined in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py).


## Installation and Entry Point Configuration

Holehe is distributed as a Python package and registers a console script during installation. In [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) (lines 15-16), the entry point is defined as:

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

```

When you run `pip install holehe`, pip generates a platform-specific wrapper script named `holehe` that invokes the `main()` function located in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). This `main` function accepts no arguments directly; instead, it parses `sys.argv` using `argparse` (lines 80-96) and delegates execution to the asynchronous `maincore` routine.


## Basic Command Line Usage

After installation, you can run Holehe from the command line by passing a target email address as the positional argument:

```bash
holehe user@example.com

```

This executes the full suite of over 120 site-modules, printing a coloured summary indicating which services have an account associated with the supplied address. The command initiates the following chain:

1. The `holehe` binary calls `holehe.core:main` as defined in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py).
2. `main()` parses command-line arguments and sets up the execution context.
3. The `trio` nursery spawns concurrent tasks via `launch_module` (lines 18-22 and 66-71 in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)) to run each OSINT check asynchronously.


## Command Line Options and Flags

The `ArgumentParser` configuration in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) supports several optional flags to control output format and execution behavior:

| Flag | Description |
|------|-------------|
| `--only-used` | Show only sites where the email is known to exist, filtering out negative results. |
| `--no-color` | Disable ANSI colour codes in terminal output. |
| `--no-clear` | Prevent the screen from being cleared before displaying results. |
| `-NP`, `--no-password-recovery` | Skip password-recovery checks on sites that support them. |
| `-C`, `--csv` | Export the results to a CSV file. |
| `-T`, `--timeout <seconds>` | Set the network request timeout (default is 10 seconds). |

**Practical examples:**

Show only successful hits, disable colours, and save to CSV:

```bash
holehe target@example.org --only-used --no-color -C

```

Increase the timeout to 20 seconds and skip password recovery probes:

```bash
holehe victim@domain.net --timeout 20 --no-password-recovery

```


## Alternative Execution Methods

You can run Holehe without installing the console script by invoking Python directly. Both methods below call the same `main` entry point and accept identical arguments.

Using the module execution syntax:

```bash
python -m holehe.core user@example.com

```

Or using the inline command flag:

```bash
python -c "import holehe.core; holehe.core.main()" user@example.com

```

These approaches are useful when testing local modifications to [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) or when running the tool in isolated environments where modifying the system path is undesirable.


## Summary

- **Entry Point:** The `holehe` command is generated from [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py) (lines 15-16) and maps to `holehe.core:main`.
- **Core Logic:** The `main()` function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) parses arguments with `argparse` (lines 80-96) and runs the async `maincore` routine.
- **Concurrency:** Execution uses a `trio` nursery to launch over 120 OSINT modules via `launch_module` (lines 66-71).
- **Flexibility:** Run via installed binary `holehe`, or directly via `python -m holehe.core`.
- **Output Control:** Use `--only-used`, `--no-color`, and `-C` to customize result presentation and export.


## Frequently Asked Questions

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

Install the package using pip: `pip install holehe`. This creates the `holehe` console script by reading the `entry_points` dictionary in [`setup.py`](https://github.com/megadose/holehe/blob/main/setup.py), which points to `holehe.core:main`. Once installed, the command is available globally in your terminal.

### What is the difference between `holehe` and `python -m holehe.core`?

Both invoke the same `main()` function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py). The `holehe` command is a convenience wrapper generated by pip, while `python -m holehe.core` executes the module directly without requiring the console script to be installed on your system path.

### How can I export Holehe results to a CSV file?

Append the `-C` or `--csv` flag to your command: `holehe email@example.com -C`. This writes the investigation results to a CSV file in the current working directory, containing columns for the service name, email existence status, and recovery method availability.

### Why does Holehe clear my terminal screen, and how do I stop it?

Holehe clears the screen by default to provide a clean output interface for the coloured results table. To prevent this behavior, add the `--no-clear` flag to your command. This preserves existing terminal content while still printing the OSINT results.