name: monitor
description: Node.js CLI for interacting with the AO Task Monitor API - get system health, alerts, logs, and task metrics for AO processes
license: MIT
compatibility: node
metadata:
audience: developers
workflow: monitoring
runtime: Node.js 18+

AO Monitor CLI

A Node.js command-line interface for the AO Task Monitor service. Query system health, view alerts, analyze logs, and monitor AO process performance.

Overview

• Location: skills/monitor/index.mjs
• Runtime: Node.js 18+
• Dependencies: None (uses built-in fetch)
• Default API: https://ao-task-monitor.onrender.com

When to Use

Use this CLI when you need to:
- Monitor AO process health and performance
- Check for system alerts or failing tasks
- View and filter execution logs
- Analyze task metrics and success rates
- Troubleshoot AO process issues
- Get quick status updates on AO processes

Authentication Setup

The CLI requires an API key set via environment variable.

Get Your API Key

Contact the AO Task Monitor service administrator to obtain your API key.

Configure Environment

For zsh (~/.zshrc):

# Add to ~/.zshrc
export AO_MONITOR_KEY="YOUR_KEY_HERE"

# Reload
source ~/.zshrc

For bash (~/.bashrc):

# Add to ~/.bashrc
export AO_MONITOR_KEY="YOUR_KEY_HERE"

# Reload
source ~/.bashrc

Temporary (current session only):

export AO_MONITOR_KEY="YOUR_KEY_HERE"

Per-command override:

node skills/monitor/index.mjs summary --token "YOUR_KEY_HERE"

Commands

summary

Get a system-wide overview of all monitored tasks.

node skills/monitor/index.mjs summary

Options:
- --period <1h|4h|8h|24h|48h> - Time window for metrics
- --include <csv> - Fields to include (e.g., counts,kpis,latency)
- --format <json|text> - Response format (default: json)

Examples:

# Default summary
node skills/monitor/index.mjs summary

# Last 24 hours, text format
node skills/monitor/index.mjs summary --period 24h --format text

# Only counts and KPIs
node skills/monitor/index.mjs summary --include counts,kpis

task

Get detailed metrics for a specific task.

node skills/monitor/index.mjs task <taskId>

Options:
- --period <1h|4h|8h|24h|48h> - Time window for metrics
- --include <csv> - Fields to include
- --format <json|text> - Response format

Examples:

# Get ao-token-info task details
node skills/monitor/index.mjs task ao-token-info

# With 48-hour window and text output
node skills/monitor/index.mjs task ao-token-info --period 48h --format text

alerts

View current system alerts and issues.

node skills/monitor/index.mjs alerts

Options:
- --period <1h|4h|8h|24h|48h> - Time window for alerts
- --format <json|text> - Response format

Examples:

# Current alerts
node skills/monitor/index.mjs alerts

# Last 4 hours, text format
node skills/monitor/index.mjs alerts --period 4h --format text

logs

View execution logs, optionally filtered by task.

# All logs
node skills/monitor/index.mjs logs

# Task-specific logs
node skills/monitor/index.mjs logs <taskId>

Options:
- --limit <n> - Maximum results (default: 100, max: 1000)
- --offset <n> - Pagination offset
- --status <success|failure|timeout> - Filter by execution status
- --error-type <string> - Filter by error message substring
- --since <isoTimestamp> - Logs after this time
- --until <isoTimestamp> - Logs before this time
- --task-id <taskId> - Filter by task ID (alternative to positional arg)

Examples:

# Recent logs
node skills/monitor/index.mjs logs

# Task-specific logs
node skills/monitor/index.mjs logs ao-token-info

# Failed executions only
node skills/monitor/index.mjs logs --status failure

# Logs with 503 errors
node skills/monitor/index.mjs logs --error-type 503

# Last 50 logs since yesterday
node skills/monitor/index.mjs logs --limit 50 --since 2024-01-01T00:00:00Z

# Paginated results
node skills/monitor/index.mjs logs --limit 100 --offset 100

docs

Retrieve API documentation from the server.

node skills/monitor/index.mjs docs

request

Make a generic API request for endpoints not covered by other commands.

node skills/monitor/index.mjs request <endpoint> <method> [body]

Arguments:
- endpoint - API path (e.g., /v1/summary)
- method - HTTP method (GET, POST, PUT, DELETE)
- body - JSON body for POST/PUT requests (optional)

Examples:

# GET request
node skills/monitor/index.mjs request /v1/summary GET

# GET with query params
node skills/monitor/index.mjs request "/v1/summary?format=text" GET

# POST with JSON body
node skills/monitor/index.mjs request /v1/api/agent POST '{"task_id":"123","status":"running"}'

# PUT request
node skills/monitor/index.mjs request /v1/api/agent/456 PUT '{"name":"Updated Agent"}'

Global Options

These options work with all commands:

Examples:

# Use different API server
node skills/monitor/index.mjs summary --base-url https://my-monitor.example.com

# Override token for single request
node skills/monitor/index.mjs alerts --token "different_key"

# Longer timeout for slow connections
node skills/monitor/index.mjs logs --timeout-ms 60000

Query Parameters Reference

For summary, task, alerts

Include field options:
- counts - Execution counts
- kpis - Key performance indicators
- latency - Response time metrics

For logs

Common Use Cases

Check System Health

# Quick overview
node skills/monitor/index.mjs summary --format text

# Check for any alerts
node skills/monitor/index.mjs alerts

Investigate Task Failures

# See if task has issues
node skills/monitor/index.mjs task ao-token-info --period 24h

# Get recent failures
node skills/monitor/index.mjs logs ao-token-info --status failure --limit 20

# Search for specific error
node skills/monitor/index.mjs logs --error-type "503" --limit 50

View Recent Activity

# Last 100 logs
node skills/monitor/index.mjs logs

# Last hour of logs
node skills/monitor/index.mjs logs --since "$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)"

# Successful runs only
node skills/monitor/index.mjs logs --status success --limit 50

Monitor Specific Task

# Task metrics
node skills/monitor/index.mjs task ao-token-info --include counts,kpis,latency

# Task logs
node skills/monitor/index.mjs logs ao-token-info --limit 50

Debug Timeouts

# Find timeout issues
node skills/monitor/index.mjs logs --status timeout

# Check latency metrics
node skills/monitor/index.mjs summary --include latency

Error Handling

Missing Authentication

If AO_MONITOR_KEY is not set and no --token provided:

Error: No authentication token provided.

Set the AO_MONITOR_KEY environment variable:
  export AO_MONITOR_KEY="your_key_here"

Or use the --token flag:
  node skills/monitor/index.mjs summary --token "your_key_here"

Authentication Failures

401 Unauthorized or 403 Forbidden:
- Verify your AO_MONITOR_KEY is correct
- Check if the key has expired
- Ensure the key has access to the requested resource

API Errors

Non-2xx responses display:
- HTTP status code
- Error message from server

Error: Request failed with status 404
Not Found: Task 'invalid-task' does not exist

Network/Timeout Errors

• Default timeout is 30 seconds
• Increase with --timeout-ms for slow connections
• Check network connectivity if requests fail

Examples Cheatsheet

# System overview
node skills/monitor/index.mjs summary

# Text format summary
node skills/monitor/index.mjs summary --format text

# Last 24h summary
node skills/monitor/index.mjs summary --period 24h

# Check alerts
node skills/monitor/index.mjs alerts

# Task details
node skills/monitor/index.mjs task ao-token-info

# Recent logs
node skills/monitor/index.mjs logs

# Task logs
node skills/monitor/index.mjs logs ao-token-info

# Failed runs
node skills/monitor/index.mjs logs --status failure

# Search errors
node skills/monitor/index.mjs logs --error-type "503"

# API docs
node skills/monitor/index.mjs docs

# Custom request
node skills/monitor/index.mjs request /v1/summary GET