# Agent Reach watch Command vs doctor Command: Differences and Use Cases

> Compare Agent Reach watch command and doctor command. Discover when to use the lightweight watch command and doctor command's comprehensive diagnostics for your platform.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: deep-dive
- Published: 2026-07-02

---

**The `watch` command provides a lightweight, one-line health check ideal for cron jobs and includes automatic version update detection, while `doctor` delivers a comprehensive Rich-formatted diagnostic report of all platform channels with optional machine-readable JSON output.**

The **Agent Reach** CLI (from the `Panniantong/Agent-Reach` repository) includes two diagnostic entry points that verify platform availability but serve distinct operational contexts. While both commands execute the same underlying health validation, they differ significantly in output formatting, side effects, and intended use cases. Understanding these architectural distinctions ensures you select the appropriate tool for automated monitoring versus interactive troubleshooting.

## Core Differences Between watch and doctor

Both commands invoke the same health-checking engine, yet they diverge in presentation and auxiliary behaviors:

- **Primary Purpose**: **`watch`** performs a quick health check suitable for scheduled tasks (e.g., cron) and verifies whether a newer release is available on GitHub. **`doctor`** generates a full diagnostic report of all supported channels and optionally emits machine-readable JSON.

- **Output Style**: `watch` prints a concise one-line status when everything is healthy (e.g., `Agent Reach: 全部正常 (12/12 渠道可用，v1.5.0 已是最新)`) or a short "监控报告" when issues exist. `doctor` always produces a multi-section Rich text report (or JSON with `--json`) that groups channels by tier, lists active backends, and highlights security warnings.

- **Side Effects**: `watch` performs only transient network requests to GitHub. `doctor` may auto-install the Agent-Reach skill file via `_install_skill(force=False)` if it is missing.

- **Update Detection**: Only `watch` queries the GitHub releases API to compare the installed version against the latest tag.

## Implementation Details in the Source Code

### CLI Entry Points and Routing

In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 127–129), the sub-parsers are defined with distinct help text:

```python
sub.add_parser("watch", help="Quick health check + update check (for scheduled tasks)")
sub.add_parser("doctor", help="Check platform availability")

```

The dispatcher (lines 149–152) routes execution to **`_cmd_watch()`** for the `watch` command and **`_cmd_doctor()`** for the `doctor` command.

### Shared Health-Checking Core

Both commands rely on **`check_all()`** implemented in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 12–35). This function:

1. Iterates over every channel returned by `agent_reach.channels.get_all_channels()`
2. Invokes each channel's `check(config)` method (defined in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py))
3. Returns a dictionary keyed by channel name containing `status`, `message`, `tier`, `backends`, and `active_backend`

### Unique Behaviors and Formatting

**`doctor`** passes the result dictionary to **`format_report()`** (lines 47–128), which builds a Rich-styled, tier-grouped text block. It never checks for updates, but may trigger `_install_skill(force=False)` (lines 92–94) to ensure the skill file is present.

**`watch`** reuses the same `check_all` call (lines 1769–1784) but handles formatting internally (lines 1810–1829). It additionally queries the GitHub releases API (lines 1894–1898) and uses **`_is_newer_version()`** (lines 1804–1806) to determine if an update is available. When a newer version exists, `watch` prints the version tag and the first few lines of the release body.

## When to Use Each Command

### Automated Monitoring and Cron Jobs

Use **`agent-reach watch`** when you need a minimal, parsable health indicator that can run unattended. The command is designed for scenarios where a zero exit code and silent output mean "all systems healthy," while any text output indicates a problem or available update.

```bash

# In crontab – run every hour, log only when something is wrong

0 * * * * agent-reach watch >> /var/log/agent-reach-watch.log 2>&1

```

Typical output when healthy:

```

Agent Reach: 全部正常 (12/12 渠道可用，v1.5.0 已是最新)

```

If a channel breaks or a new version appears, the output expands to show the specific failure and update notice.

### Interactive Troubleshooting and Auditing

Use **`agent-reach doctor`** when you need human-readable diagnostics or detailed configuration analysis. The Rich-formatted report includes:

- Grouped channel listings by tier (ready-to-use vs. optional)
- Active backend identification
- Security warnings about file permissions (e.g., overly permissive `~/.agent-reach/config.yaml`)

```bash
agent-reach doctor

```

Sample output excerpt:

```

Agent Reach 状态
========================================
图例：✅ 可用  [! ] 已装但需配置/登录  [X] 未安装

✅ 装好即用：
  ✅ YouTube — ...  
  ✅ Reddit — ...  

可选渠道（已安装）：
  ✅ Twitter — ...  

状态：10/12 个渠道可用
[! ]  安全提示：config.yaml 权限过宽（其他用户可读）
   修复：chmod 600 ~/.agent-reach/config.yaml

```

### Machine-Readable Integration

For scripts or external monitoring systems that consume JSON, use `doctor` with the `--json` flag:

```bash
agent-reach doctor --json | jq .

```

This outputs the raw status dictionary (as generated by `check_all`) without Rich formatting:

```json
{
  "youtube": {
    "status": "ok",
    "name": "YouTube",
    "message": "可用",
    "tier": 0,
    "backends": ["yt-dlp"],
    "active_backend": "yt-dlp"
  },
  "reddit": {
    "status": "off",
    "name": "Reddit",
    "message": "未登录 (需要 cookies)",
    "tier": 1,
    "backends": ["opencli", "rdt"],
    "active_backend": null
  }
}

```

## Summary

- **`watch`** is a thin wrapper around the health engine with added GitHub release checks and minimal output, ideal for cron-based monitoring.
- **`doctor`** provides comprehensive Rich reports (or JSON) and may auto-install missing skills, making it suited for interactive debugging.
- Both commands execute **`check_all()`** in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), but **`doctor`** uses **`format_report()`** for presentation while **`watch`** implements its own concise formatting.
- Only **`doctor`** inspects configuration file permissions and may modify the filesystem via **`_install_skill()`**.
- Only **`watch`** detects newer versions via the GitHub API using **`_is_newer_version()`**.

## Frequently Asked Questions

### Does the watch command modify any files?

No. According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), `watch` performs only transient network requests to GitHub for version checking. Unlike `doctor`, it never invokes `_install_skill()` or writes to the filesystem beyond optional logging you configure externally.

### Can I use doctor in a CI/CD pipeline?

Yes, but you should use the **`--json`** flag to obtain machine-readable output. The standard Rich-formatted text includes terminal color codes and box-drawing characters that may parse poorly in CI logs. The JSON output provides the raw status dictionary from `check_all()` suitable for programmatic evaluation.

### Why does doctor show security warnings that watch doesn't?

The `doctor` command uses **`format_report()`** in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) to inspect `~/.agent-reach/config.yaml` permissions and warns if the file is readable by other users. The `watch` command intentionally omits this check to maintain minimal output and faster execution for automated monitoring scenarios.

### How do I parse Agent Reach health status programmatically?

For script integration, use **`agent-reach doctor --json`**. This outputs the complete health dictionary without formatting noise, allowing tools like `jq` to extract specific channel statuses, backend availability, or configuration messages. The `watch` command is designed for human-readable summaries and lacks a structured output mode.