# Main Entry Point for the Doom Application: A Complete Guide

> Discover the main entry point of the Doom application. Explore the run() function in src/doom/__main__.py invoked by the doom console script. Your complete guide awaits.

- Repository: [000pp/doom](https://github.com/000pp/doom)
- Tags: how-to-guide
- Published: 2026-02-22

---

**The main entry point for the Doom application is the `run()` function in [`src/doom/__main__.py`](https://github.com/000pp/doom/blob/main/src/doom/__main__.py), invoked via the `doom` console script defined in [`pyproject.toml`](https://github.com/000pp/doom/blob/main/pyproject.toml).**

The Doom application is a terminal user interface (TUI) built with the `textual` framework, hosted in the `000pp/doom` repository. Understanding how the application initializes is essential for developers contributing to the codebase or embedding the tool within larger workflows. This guide examines the entry point configuration, implementation details, and multiple invocation methods supported by the source code.

## How the Entry Point is Defined in pyproject.toml

The application registers its command-line interface through the `[project.scripts]` table in [`pyproject.toml`](https://github.com/000pp/doom/blob/main/pyproject.toml). This configuration creates a platform-agnostic executable during package installation.

```toml
[project.scripts]
doom = "doom.__main__:run"

```

This declaration maps the `doom` command to the `run` function located in the `doom.__main__` module. When a user executes `doom` in their shell, Python imports [`src/doom/__main__.py`](https://github.com/000pp/doom/blob/main/src/doom/__main__.py) and calls the `run()` function directly, passing no arguments by default.

## The run() Function: Core Application Launcher

The actual bootstrapping logic resides in [`src/doom/__main__.py`](https://github.com/000pp/doom/blob/main/src/doom/__main__.py). According to the source code at lines 18–23, the `run()` function instantiates the main application class and starts the event loop.

```python

# src/doom/__main__.py

def run():
    app = DoomApp()
    app.run()

```

The `DoomApp` class extends `textual.app.App`, which provides the asynchronous event loop and widget management system. By encapsulating the initialization within a dedicated `run()` function, the codebase supports both CLI execution and programmatic imports without side effects at the module level.

## Three Ways to Launch the Doom Application

The repository supports multiple invocation patterns, each leveraging the same underlying entry point.

### Using the Installed Console Script

After installing the package via `pip install .`, the `doom` command becomes available in your environment:

```bash
doom

```

This executes the script defined in [`pyproject.toml`](https://github.com/000pp/doom/blob/main/pyproject.toml), which resolves to `doom.__main__:run`.

### Running as a Module with python -m

You can invoke the application without installing the console script by treating the package as an executable module:

```bash
python -m doom

```

Python executes [`src/doom/__main__.py`](https://github.com/000pp/doom/blob/main/src/doom/__main__.py) as the `__main__` module, automatically calling the `run()` function at the bottom of the file (if present) or allowing manual execution of the function.

### Importing and Invoking Programmatically

For testing, embedding, or automation workflows, import the entry point directly:

```python
from doom.__main__ import run

if __name__ == "__main__":
    run()  # Starts the DoomApp GUI

```

This pattern is particularly useful for integration tests that need to mock the `DoomApp` instance or capture the event loop initialization.

## Summary

- The **main entry point** is the `run()` function in [`src/doom/__main__.py`](https://github.com/000pp/doom/blob/main/src/doom/__main__.py), which instantiates `DoomApp` and starts the textual event loop.
- **Entry configuration** resides in [`pyproject.toml`](https://github.com/000pp/doom/blob/main/pyproject.toml) under `[project.scripts]`, mapping the `doom` command to `doom.__main__:run`.
- **Three invocation methods** are supported: the installed `doom` CLI command, `python -m doom`, and direct programmatic import of the `run()` function.

## Frequently Asked Questions

### Where is the Doom application entry point defined?

The entry point is defined in [`pyproject.toml`](https://github.com/000pp/doom/blob/main/pyproject.toml) within the `[project.scripts]` section, which registers the `doom` command to execute the `run` function in `doom.__main__`. This configuration is located at lines 22–24 of the configuration file.

### Can I run the Doom application without installing it as a package?

Yes, you can execute the application directly using `python -m doom` from the repository root. This command treats the `doom` directory as a module and executes [`src/doom/__main__.py`](https://github.com/000pp/doom/blob/main/src/doom/__main__.py), which calls the `run()` function to launch the interface.

### What happens when the `run()` function is called?

The `run()` function in [`src/doom/__main__.py`](https://github.com/000pp/doom/blob/main/src/doom/__main__.py) creates an instance of the `DoomApp` class and invokes its `run()` method. This initializes the textual framework's event loop and renders the terminal user interface, starting with the login screen defined in the application's screen stack.