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

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 (lines 127–129), the sub-parsers are defined with distinct help text:

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

# 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)

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:

agent-reach doctor --json | jq .

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

{
  "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, 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, 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 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.

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