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

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 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.

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.

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.

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.

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.

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.

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 – Contains the public command dispatcher and the _cmd_doctor helper function that orchestrates the health check and output formatting.
• 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 – 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.

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