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

bash

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

# Reload
source ~/.zshrc

For bash (~/.bashrc):

bash

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

# Reload
source ~/.bashrc

Temporary (current session only):

bash

export AO_MONITOR_KEY="YOUR_KEY_HERE"

Per-command override:

bash

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

Commands

summary

Get a system-wide overview of all monitored tasks.

bash

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:

bash

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

bash

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:

bash

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

bash

node skills/monitor/index.mjs alerts

Options:

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

Examples:

bash

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

bash

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

bash

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

bash

node skills/monitor/index.mjs docs

request

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

bash

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:

bash

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

Option	Description
`--base-url <url>`	Override API base URL
`--token <token>`	Override auth token (instead of AO_MONITOR_KEY)
`--timeout-ms <ms>`	Request timeout in milliseconds (default: 30000)
`--help, -h`	Show help message

Examples:

bash

# 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

Parameter	Values	Description
`--period`	`1h` , `4h` , `8h` , `24h` , `48h`	Time window for metrics
`--include`	CSV of fields	Fields to include in response
`--format`	`json` , `text`	Response format

Include field options:

```
counts
```
- Execution counts
```
kpis
```
- Key performance indicators
```
latency
```
- Response time metrics

For logs

Parameter	Type	Description
`--limit`	integer	Max results (1-1000, default: 100)
`--offset`	integer	Pagination offset
`--status`	string	`success` , `failure` , or `timeout`
`--error-type`	string	Filter by error substring
`--since`	ISO timestamp	Logs after this time
`--until`	ISO timestamp	Logs before this time
`--task-id`	string	Filter by task ID

Common Use Cases

Check System Health

bash

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

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

Investigate Task Failures

bash

# 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

bash

# 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

bash

# 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

bash

# 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

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

bash

# 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

monitor

NPX Install

Tags

SKILL.md Content

AO Monitor CLI

Overview

When to Use

Authentication Setup

Get Your API Key

Configure Environment

Commands

summary

task

alerts

logs

docs

request

Global Options

Query Parameters Reference

For summary, task, alerts

For logs

Common Use Cases

Check System Health

Investigate Task Failures

View Recent Activity

Monitor Specific Task

Debug Timeouts

Error Handling

Missing Authentication

Authentication Failures

API Errors

Network/Timeout Errors

Examples Cheatsheet