# How to Run the Doctor Command Programmatically in Python for Agent Reach

> Learn to run the Agent Reach doctor command programmatically in Python. Access CLI output or raw data for custom reports using agent_reach.cli and agent_reach.doctor.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-11

---

**You can run the Agent Reach doctor command programmatically by importing `_cmd_doctor` from `agent_reach.cli` for CLI-equivalent output, or use `check_all` and `format_report` from `agent_reach.doctor` for raw data access and custom reporting.**

Agent Reach exposes its CLI commands as standard Python functions, enabling you to run the doctor command programmatically without spawning subprocesses. The Panniantong/Agent-Reach repository implements the health-check logic across three modular files that handle command dispatch, diagnosis, and configuration management. This architecture allows you to embed system health checks directly into your applications, scheduled tasks, or web services while maintaining full access to error-tolerant validation logic.

## Two Approaches to Running the Doctor Command Programmatically

Agent Reach provides two distinct pathways to execute health checks from Python code, depending on whether you need formatted output or raw data.

### Option 1: Using the High-Level CLI Helper

Import `_cmd_doctor` from [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) to reproduce exactly what the CLI does when you run `agent-reach doctor`. This internal helper automatically instantiates the user configuration and renders the formatted Rich report to stdout.

```python
from agent_reach.cli import _cmd_doctor

# Runs the complete doctor check with formatted terminal output

_cmd_doctor()

```

### Option 2: Using the Lower-Level Doctor API

Import `check_all` and `format_report` from `agent_reach.doctor` alongside `Config` from `agent_reach.config` to access the raw status dictionary. This approach lets you process health data programmatically, log results to external systems, or render custom reports.

```python
from agent_reach.doctor import check_all, format_report
from agent_reach.config import Config

cfg = Config()                    # Loads ~/.agent-reach/config.yaml

status = check_all(cfg)           # Returns {channel_name: {...}, ...}

```

## Complete Code Examples for Programmatic Execution

These examples demonstrate how to run the doctor command programmatically in Python for Agent Reach across common use cases.

**Example 1:** Directly invoke the CLI helper to mirror the standard command-line experience.

```python
from agent_reach.cli import _cmd_doctor

# Execute the doctor and print the formatted Rich report (default behavior)

_cmd_doctor()

```

**Example 2:** Extract the raw status dictionary for logging or further analysis.

```python
from agent_reach.doctor import check_all
from agent_reach.config import Config

cfg = Config()                     # loads ~/.agent-reach/config.yaml

status = check_all(cfg)            # Returns JSON-compatible dict

print(status)

```

**Example 3:** Print the formatted text report using the same rendering logic as the CLI.

```python
from agent_reach.doctor import check_all, format_report
from agent_reach.config import Config

cfg = Config()
status = check_all(cfg)
print(format_report(status))

```

**Example 4:** Generate a machine-readable JSON report equivalent to the `--json` flag.

```python
import json
from agent_reach.doctor import check_all
from agent_reach.config import Config

cfg = Config()
status = check_all(cfg)
print(json.dumps(status, ensure_ascii=False, indent=2))

```

## Key Source Files in Agent Reach

Understanding the module structure helps you navigate the codebase when running the doctor command programmatically.

- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Contains the public command dispatcher and the `_cmd_doctor` helper function that orchestrates the health check and output formatting.
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)** – Implements the core health-check logic through `check_all()` and report formatting via `format_report()`, operating independently of the CLI layer.
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** – Defines the `Config` class that reads `~/.agent-reach/config.yaml`, providing the configuration object required by both the high-level and low-level APIs.

## Summary

- Import `_cmd_doctor` from `agent_reach.cli` to execute the doctor check with identical behavior to the `agent-reach doctor` terminal command.
- Use `check_all` and `format_report` from `agent_reach.doctor` for programmatic access to health status data and custom reporting workflows.
- Instantiate `Config` from `agent_reach.config` to load user configuration from `~/.agent-reach/config.yaml` automatically.
- All programmatic approaches run in-process without subprocess overhead, making them suitable for embedding in applications, scheduled jobs, or web services.

## Frequently Asked Questions

### How do I get JSON output when running the doctor command programmatically?

When using the lower-level API, `check_all()` returns a standard Python dictionary that you can serialize with `json.dumps()`. Unlike the CLI `--json` flag which handles serialization internally, the programmatic approach gives you control over formatting options like `indent` and `ensure_ascii` before producing the final string output.

### What is the difference between `_cmd_doctor` and `check_all`?

`_cmd_doctor` is a high-level wrapper that instantiates `Config`, calls `check_all`, and prints the formatted report to stdout, mirroring the CLI experience exactly. `check_all` is the underlying function that performs the actual health checks and returns a raw status dictionary, allowing you to process the data or handle output differently than the default Rich-formatted terminal display.

### Can I run the doctor check against a custom configuration file?

Yes. While `Config()` loads `~/.agent-reach/config.yaml` by default, you can manipulate the configuration object before passing it to `check_all(cfg)`. The `Config` class accepts initialization parameters or environment variables that override default paths, allowing you to specify alternative configuration files programmatically when instantiating the class.

### Is it safe to import underscore-prefixed functions like `_cmd_doctor`?

While `_cmd_doctor` follows the Python convention indicating an internal implementation detail, it is the officially exposed entry point for programmatic CLI execution in Agent Reach. The function signature remains stable across versions because it serves as the underlying implementation for the actual CLI command, making it safe to import for production use when you need exact CLI parity.