# How to Find and Run the Main Script for DeepTutor

> Discover how to find and run the main script for DeepTutor. Learn to launch the CLI or web interface by locating key Python files in the DeepTutor repository.

- Repository: [✨Data Intelligence Lab@HKU✨/DeepTutor](https://github.com/HKUDS/DeepTutor)
- Tags: how-to-guide
- Published: 2026-04-08

---

**DeepTutor’s primary entry point is a Typer-based CLI defined in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py), while [`scripts/start_web.py`](https://github.com/HKUDS/DeepTutor/blob/main/scripts/start_web.py) launches the full web interface by orchestrating the FastAPI backend and Next.js frontend.**

The HKUDS/DeepTutor repository provides distinct execution paths depending on whether you need headless command-line interaction or a complete graphical interface. Understanding the exact file locations and their roles ensures you invoke the correct entry point for your use case. This guide identifies the main scripts required to run DeepTutor and explains how they interact with the underlying API and frontend components.

## CLI Entry Point: deeptutor_cli/main.py

The primary command-line interface is implemented in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py). This file initializes a **Typer** application that registers sub-commands—including `chat`, `bot`, `kb`, and the `run` command—and exposes methods for executing capabilities in a single turn without launching a persistent server.

When the package is installed, it exposes a `deeptutor` console script mapped to this module. You can invoke specific capabilities directly from your terminal without starting the full web stack.

Run a capability using the installed console script:

```bash
deeptutor run chat "Explain the Fourier transform" -t rag --kb my-kb

```

Alternatively, invoke the module directly without installation:

```bash
python -m deeptutor_cli.main run chat "Explain the Fourier transform" -t rag --kb my-kb

```

## Web Interface Launcher: scripts/start_web.py

To start the complete web application, use the helper script **[`scripts/start_web.py`](https://github.com/HKUDS/DeepTutor/blob/main/scripts/start_web.py)**. This convenience script reads port configurations from the project’s `.env` file and concurrently launches both the API server and the frontend interface.

Specifically, the script calls **`deeptutor.api.run_server`** to initialize the FastAPI backend and spawns the Next.js frontend process. It automatically handles port wiring between the backend (typically `localhost:8000`) and the frontend (typically `localhost:3000`), printing accessible URLs upon successful startup.

Start the full web stack in one terminal:

```bash
python scripts/start_web.py

```

Expected output showing the service endpoints:

```

Backend   http://localhost:8000
Frontend  http://localhost:3000
Open http://localhost:3000 in your browser.

```

## Key Backend Component: deeptutor/api/run_server.py

While [`scripts/start_web.py`](https://github.com/HKUDS/DeepTutor/blob/main/scripts/start_web.py) handles orchestration, the actual **FastAPI** server implementation resides in [`deeptutor/api/run_server.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/run_server.py). This module defines the REST and WebSocket endpoints that power the chat interface. When using the web launcher or running the API server independently, this file contains the core server logic that processes incoming requests.

## Summary

- **[`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py)** defines the Typer-based CLI and registers sub-commands including `run` for single-turn capability execution.
- **[`scripts/start_web.py`](https://github.com/HKUDS/DeepTutor/blob/main/scripts/start_web.py)** serves as the unified launcher for the web interface, starting both the backend and frontend components.
- The backend server is implemented in **[`deeptutor/api/run_server.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/run_server.py)**, which provides the FastAPI application instance.
- Port configurations are automatically read from the `.env` file when using the web launcher script.

## Frequently Asked Questions

### Where is the main script to run DeepTutor from the command line?

The main CLI entry point is [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py), which implements the Typer application. You can invoke it via the `deeptutor` console script when installed, or run `python -m deeptutor_cli.main` directly from the repository root.

### How do I launch the DeepTutor web interface?

Execute `python scripts/start_web.py` to start the full web interface. This script launches the FastAPI backend via `deeptutor.api.run_server` and the Next.js frontend simultaneously, reading environment variables from `.env` to configure ports.

### Can I use DeepTutor without starting the web server?

Yes. The CLI entry point supports single-turn execution via the `run` sub-command, allowing you to query capabilities directly without launching the persistent API server or frontend.

### What server does the web launcher script actually start?

The [`scripts/start_web.py`](https://github.com/HKUDS/DeepTutor/blob/main/scripts/start_web.py) script imports and executes the `run_server` function from [`deeptutor/api/run_server.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/api/run_server.py), which initializes the FastAPI application that handles REST and WebSocket connections for the chat interface.