# How to Perform a Health Check with the Agent Reach Doctor Command

> Learn how to run the agent reach doctor command to quickly check and confirm your registered channels like Twitter, Reddit, and YouTube are properly configured and ready to use.

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

---

**Run `agent-reach doctor` to verify that every registered channel (Twitter, Reddit, YouTube, etc.) is properly configured and ready for use.**

The `doctor` command is the built-in diagnostic tool for the Agent Reach framework. It probes all configured channels, validates authentication states, and identifies misconfigurations before they cause runtime failures. This guide covers both CLI usage and programmatic access based on the Panniantong/Agent-Reach source code.

## Running the Doctor Command

Agent Reach provides a first-class CLI entry point for health diagnostics. The command is implemented in [[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) within the `_cmd_doctor` function (around line 1447).

### Basic Usage

Execute the standard health check from your terminal:

```bash
agent-reach doctor

```

Alternatively, invoke the module directly:

```bash
python -m agent_reach.cli doctor

```

The output displays a tiered summary (0 = zero-config, 1 = optional key-login, 2 = complex setup) showing which backends are authenticated and operational:

```

✅ Ready to use:
  ✅ Twitter  — Logged in
  [!] Reddit  — Login required
Status: 7/9 channels available

```

### JSON Output

For CI/CD pipelines or automated monitoring, use the `--json` flag to emit machine-readable results:

```bash
agent-reach doctor --json

```

This outputs a structured dictionary containing status, tier levels, active backends, and descriptive messages for every registered channel.

## How the Health Check Works Internally

The diagnostic flow follows a three-stage pipeline defined in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py).

### Configuration Loading

First, `Config()` initializes by reading `~/.agent-reach/config.yaml`. This determines which channels are enabled and what credentials are available. According to the source, if the config file has world-readable permissions, the doctor emits a security warning (lines 109-124) before proceeding with checks.

### Channel Verification

The `check_all(config)` function (implemented at line 12 of [[`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) iterates over every registered channel:

1. Each channel implements a `check(config)` method returning a `(status, message)` tuple.
2. Common statuses include `"ok"`, `"warn"`, `"off"`, and `"error"`.
3. Exceptions within individual channels are isolated so one broken backend cannot crash the entire report.

Individual channel implementations (e.g., [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py), [`agent_reach/channels/reddit.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/reddit.py)) contain the backend-specific logic for validating tokens and connectivity.

### Report Rendering

Results are formatted based on output mode:

- **Human-readable**: `format_report(results)` (lines 47-99) generates a Rich-markup table with color-coded status indicators.
- **Machine-readable**: `json.dumps` serializes the raw results dictionary.

After printing the report, the CLI automatically triggers `_install_skill()` to ensure the Agent Reach skill is registered locally.

## Programmatic Health Checks

You can import the health-checking logic directly into Python scripts without invoking the subprocess.

### Generating a Standard Report

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

cfg = Config()
results = check_all(cfg)            # Dictionary of channel statuses

print(format_report(results))       # Pretty output matching CLI

```

### Filtering for Failed Channels

To isolate only the channels requiring attention:

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

failures = {k: v for k, v in check_all(Config()).items()
            if v["status"] in ("warn", "off", "error")}
print(f"Problematic channels: {list(failures)}")

```

This pattern is useful for building custom alerting systems that monitor specific authentication states.

## Security and Post-Check Actions

The doctor performs two critical housekeeping tasks:

- **Permission Validation**: Detects if [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/config.yaml) is world-readable and warns the user to restrict file permissions.
- **Skill Auto-Installation**: Runs `_install_skill()` after every health check to ensure the local Agent Reach skill is synchronized with the current environment configuration.

## Summary

- **Entry point**: Use `agent-reach doctor` or the `_cmd_doctor` handler in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).
- **Core logic**: The `check_all()` function in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) validates every channel's `check()` method.
- **Output formats**: Human-readable tables via `format_report()`, or JSON with `--json`.
- **Configuration**: Reads from `~/.agent-reach/config.yaml` and warns on insecure permissions.
- **Automation**: Call `check_all(Config())` programmatically to integrate health data into custom workflows.

## Frequently Asked Questions

### What does the "need login" status mean?

This indicates a configured channel is enabled but lacks valid authentication credentials. Tier 1 channels (like Reddit) require manual login or API key configuration in `~/.agent-reach/config.yaml`, whereas Tier 0 channels (like Twitter in some modes) work without credentials.

### Can I run health checks without the CLI?

Yes. Import `check_all` from `agent_reach.doctor` and pass it a `Config` instance. This returns a dictionary of statuses without triggering the CLI's auto-installation routine, making it ideal for headless server environments.

### Why does the doctor command auto-install skills?

The `_install_skill()` call ensures that any configuration changes detected during the health check are immediately reflected in the installed Agent Reach skill. This keeps the framework's runtime behavior synchronized with its configuration state.

### How are channel tiers determined?

Tiers classify setup complexity: **Tier 0** channels work out-of-the-box with zero configuration; **Tier 1** requires optional keys or login; **Tier 2** demands complex setup (e.g., custom endpoints or OAuth flows). The doctor groups output by these tiers to help prioritize configuration efforts.