# Agent Reach watch Command: Purpose and Functionality for Scheduled Health Checks

> Discover the Agent Reach watch command purpose and functionality for automated health checks and software update verification. Learn how it runs silently and alerts you to issues.

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

---

**The `watch` command performs automated health checks on all configured channels and verifies software updates, designed to run silently during healthy states and only output when problems or updates exist.**

The **Agent Reach** CLI provides a specialized `watch` sub-command specifically engineered for production monitoring and cron-based automation. Unlike interactive commands, this utility orchestrates diagnostic routines that validate channel connectivity and software currency while minimizing noise during routine successful executions.

## How the watch Command Works

The command is implemented as a lightweight orchestration routine in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) that aggregates diagnostic data from across the system without user intervention.

### Entry Point and Command Registration

The `watch` sub-command is registered in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines 127–151, dispatching execution to the internal `_cmd_watch` function.

```python
def _cmd_watch():
    """Quick health check + update check, designed for scheduled tasks.

    Only outputs problems. If everything is fine, outputs a single line.
    """

```

This entry point initializes the monitoring sequence by loading user configuration and preparing result aggregation structures before executing the dual verification routines.

### Channel Health Diagnostics

Inside `_cmd_watch` (lines 44–53), the system builds a `Config` object and invokes the doctor's `check_all` helper imported from `agent_reach/doctor`.

```python
from agent_reach.doctor import check_all
...
config = Config()
issues = []
results = check_all(config)          # ← asks every channel to run its own `check`

```

The `check_all` function (implemented at lines 12–20 in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) iterates over the registry of channel classes returned by `get_all_channels()`. It invokes each channel's `check` method individually, wrapping calls in exception handling to ensure a single misbehaving channel cannot abort the entire health report.

Each channel returns a dictionary containing a `status` field (`ok`, `warn`, `off`, or `error`) and a human-readable `message`. The `_cmd_watch` function aggregates any non-`ok` statuses into an issues list (lines 56–62) for the final report.

### Version Update Detection

Following health diagnostics, `_cmd_watch` queries the GitHub Releases API to detect available software updates (lines 66–73 in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)).

```python
resp, err, _ = _github_get_with_retry(
    "https://api.github.com/repos/Panniantong/Agent-Reach/releases/latest",
    timeout=10,
    retries=2,
)
if not err and resp and resp.status_code == 200:
    data = resp.json()
    latest = data.get("tag_name", "").lstrip("v")
    if latest and _is_newer_version(latest, __version__):
        update_available = True
        new_version = latest
        release_body = data.get("body", "")

```

The helper `_is_newer_version` (lines 58–66) performs semantic version comparison to prevent false downgrade prompts, ensuring only genuinely newer releases trigger notifications.

### Output Logic and Exit Behavior

The command implements conditional output optimized for automated scheduling. If no health issues and no version updates are found, the system prints a single concise line indicating complete system health (lines 81–84).

When problems exist or updates are available, the command generates a structured report (lines 85–100) listing healthy channel counts, specific error messages, and new version details with release notes excerpts. This design ensures that cron systems or monitoring alerts only trigger when actionable information exists.

## Implementing Scheduled Monitoring

The `watch` command is optimized for cron-style automation because it produces no output during standard healthy operation, preventing alert fatigue.

### Manual Execution

Run a one-off health check from the terminal:

```bash
agent-reach watch

```

Typical successful output:

```

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

```

Example output when channels fail and updates exist:

```

Agent Reach 监控报告
========================================
版本: v1.5.0  |  渠道: 10/12
[X] Twitter：未登录
! Reddit：需要 API token
...
新版本可用: v1.6.0
    • 修复 XSS 漏洞
    • 新增 TikTok 支持
  更新（一句话发给 Agent 即可完整更新）:
    帮我更新 Agent Reach：https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/update.md

```

### Cron Configuration

Configure automated monitoring by adding the command to your system's crontab:

```cron

# Run health check every hour, email on any output

0 * * * * /usr/local/bin/agent-reach watch | mail -s "Agent Reach health" admin@example.com

```

This configuration executes hourly, emailing administrators only when the command emits output—meaning only when health issues emerge or software updates become available.

## Summary

- The `watch` command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) provides silent health monitoring optimized for scheduled tasks and cron jobs.
- **Channel health checks** iterate through all registered channels via `check_all` in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), catching exceptions to isolate individual channel failures.
- **Version checking** queries GitHub's latest release API with semantic version comparison via `_is_newer_version` to avoid false positives.
- The command produces output only when issues exist or updates are available, making it ideal for automated alerting systems that monitor stderr/stdout.
- Each channel implements its own `check` method, allowing modular diagnostic logic specific to each integration (e.g., Twitter, Reddit).

## Frequently Asked Questions

### What triggers the watch command to produce output?

The `watch` command remains silent and outputs only a single confirmation line when all channels report `ok` status and no software updates are available. It produces detailed reports only when channel health checks return `warn`, `off`, or `error` statuses, or when the GitHub API indicates a newer version exists than the currently installed `__version__`.

### How does the watch command handle individual channel failures?

According to the implementation in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 12–20), the `check_all` function wraps each channel's `check` method in a try-except block. This isolation ensures that exceptions thrown by one channel do not terminate the entire health check process, allowing the command to report comprehensive partial system health rather than failing completely on the first error.

### Where is the watch command defined in the codebase?

The command entry point is defined in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) at lines 127–151, where the CLI parser registers the `watch` sub-command. The core orchestration logic resides in the `_cmd_watch` function spanning lines 44–100, which coordinates configuration loading, health diagnostics via the doctor module, and version checking against the GitHub API.

### What version comparison logic does watch use?

The command utilizes a private helper function `_is_newer_version` implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 58–66) to perform semantic version comparison. This ensures that only genuinely newer releases trigger update notifications, preventing false alerts for older or equivalent version strings that might be returned by the GitHub Releases API.