# Agent Reach watch vs doctor Commands: Key Differences Explained

> Understand Agent Reach watch vs doctor commands. Learn how doctor performs a full health check while watch checks health and detects version updates for automation.

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

---

**The `doctor` command performs a comprehensive health check of all platforms, while `watch` combines a quick health check with version update detection for automated scheduling.**

The `agent-reach` CLI from the **Panniantong/Agent-Reach** repository provides two diagnostic commands that appear similar but serve distinct operational needs. Understanding the difference between the `watch` and `doctor` commands helps you choose the right tool for interactive debugging versus automated monitoring.

## Primary Purpose and Use Cases

Both commands validate your environment, but they target different workflows.

### doctor Command

The `doctor` command runs a **full health check** of every supported platform. It reports the status of each channel—including cookies, API keys, and required tools—and generates a detailed diagnostic report. Use this for interactive debugging when setting up Agent Reach or troubleshooting configuration issues.

### watch Command

The `watch` command performs a **quick health check** while also verifying whether a newer version of Agent Reach is available. Designed for periodic automated runs (such as cron jobs), it offers a lightweight validation that keeps your deployment current without verbose output.

## Implementation Details

The functional differences stem from distinct handler implementations in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

The ** `_cmd_doctor`** handler (starting at line 1476) loads the configuration, invokes `agent_reach.doctor.check_all`, and prints a formatted report via `format_report`. It also auto-installs the skill if missing, ensuring the environment is fully initialized before checking health.

The ** `_cmd_watch`** handler (starting at line 1768) first executes the update-check routine (`_cmd_check_update`) and then runs the same core health-check logic as `doctor`. This makes `watch` a wrapper that adds version awareness to the diagnostic process.

## CLI Registration and Help Text

The commands are registered in the CLI with distinct help descriptions that reflect their intended use.

The `doctor` command is added via `sub.add_parser("doctor", …)` with help text stating "Check platform availability" (see lines 92‑96). The `watch` command is registered via `sub.add_parser("watch", …)` with help text describing it as "Quick health check + update check (for scheduled tasks)" (see lines 127‑129).

## Output and Automation Characteristics

| Characteristic | doctor | watch |
|----------------|--------|-------|
| **Report Detail** | Multi-line formatted report with JSON option (`--json`) | Concise health summary |
| **Version Check** | No | Yes (checks for newer releases) |
| **Best For** | Manual diagnostics and setup validation | Automated monitoring and CI/CD pipelines |
| **Verbosity** | High (shows every platform status) | Low (minimal output for logs) |

## Practical Examples

Run a comprehensive diagnostic interactively to see which platforms are correctly configured:

```bash
agent-reach doctor

```

This displays the status of every channel and prints a formatted report highlighting any missing dependencies.

For automated environments, schedule the lightweight check that also monitors for updates:

```bash
agent-reach watch

```

This prints a brief health line and notifies you if a newer version exists, making it ideal for cron jobs or systemd timers.

## Summary

- **`doctor`** provides exhaustive platform health checks via `check_all` and `format_report` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), intended for manual debugging.
- **`watch`** executes `_cmd_check_update` followed by the same health logic, targeting scheduled automation with minimal output.
- Both commands share core diagnostic logic, but `watch` adds version detection and is optimized for non-interactive runs.
- Use `doctor` when configuring Agent Reach; use `watch` when monitoring production deployments.

## Frequently Asked Questions

### What is the main technical difference between watch and doctor in Agent Reach?

Both commands call the underlying `check_all` and `format_report` functions from the `agent_reach.doctor` module, but the `watch` handler at line 1768 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) additionally invokes `_cmd_check_update` to detect new releases, whereas the `doctor` handler at line 1476 focuses solely on comprehensive platform validation.

### When should I use doctor instead of watch?

Use `doctor` when you need detailed visibility into platform configurations during initial setup or troubleshooting. It provides granular status reports for every channel including API keys, cookies, and tool availability, which is essential for interactive debugging.

### Is watch suitable for CI/CD automation?

Yes. The `watch` command is explicitly designed for scheduled tasks and automation because it performs a quick health verification without verbose output while checking for available updates. Its concise reporting prevents log bloat in automated pipelines.

### Do both commands auto-install missing skills?

The `doctor` command includes logic to auto-install the skill if it is missing during its execution flow. The `watch` command focuses primarily on health status and version checking, delegating full environment setup to the `doctor` logic when health checks are initiated.