agilemonitor-cli/README.md

Command-line interface for AgileMonitor - Monitor your websites from the terminal

# AgileMonitor CLI

> Command-line interface for [AgileMonitor](https://agilemonitor.net) - Monitor your websites from the terminal

[![npm version](https://badge.fury.io/js/agilemonitor-cli.svg)](https://www.npmjs.com/package/agilemonitor-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- ✅ **Manage monitors** from your terminal
- ✅ **View real-time status** and check history
- ✅ **Add/remove monitors** with a single command
- ✅ **List alerts** and site status
- ✅ **Beautiful colored output** with spinners and progress indicators
- ✅ **Fast and lightweight** - works on Mac, Linux, Windows
- ✅ **Secure API key storage** in your home directory

## Installation

```bash
npm install -g agilemonitor-cli
```

**Requirements**: Node.js 14.0.0 or higher

## Quick Start

```bash
# 1. Login with your API key
agilemonitor login am_live_your_api_key_here

# 2. Add your first monitor
agilemonitor add https://mysite.com

# 3. List all monitors
agilemonitor list

# 4. Check status
agilemonitor status 1
```

## Getting Your API Key

1. Go to [https://agilemonitor.net/api-keys](https://agilemonitor.net/api-keys)
2. Click "Create API Key"
3. Copy the key (shown only once!)
4. Run `agilemonitor login <your-key>`

**Note**: API access requires a PRO or TEAM plan.

## Commands

### Authentication

#### `agilemonitor login <api-key>`
Save your API key for authentication

```bash
agilemonitor login am_live_abc123xyz
```

#### `agilemonitor logout`
Remove saved API key

```bash
agilemonitor logout
```

#### `agilemonitor whoami`
Show current user info and subscription details

```bash
agilemonitor whoami
```

---

### Monitor Management

#### `agilemonitor add <url> [options]`
Add a new monitor

**Options:**
- `-n, --name <name>` - Monitor name (defaults to URL)
- `-i, --interval <seconds>` - Check interval in seconds (default: 300)
- `-t, --timeout <seconds>` - Request timeout in seconds (default: 10)

**Examples:**
```bash
# Basic
agilemonitor add https://mysite.com

# With custom name and interval
agilemonitor add https://api.myapp.com --name "Production API" --interval 60

# With all options
agilemonitor add https://mysite.com -n "My Site" -i 300 -t 10
```

#### `agilemonitor list [options]`
List all your monitors

**Alias:** `ls`

**Options:**
- `-a, --all` - Show inactive monitors too

**Examples:**
```bash
# Show active monitors
agilemonitor list

# Show all monitors (including inactive)
agilemonitor list --all
```

#### `agilemonitor status <id>`
Get detailed status of a monitor

```bash
agilemonitor status 1
```

#### `agilemonitor remove <id> [options]`
Remove a monitor

**Alias:** `rm`

**Options:**
- `-y, --yes` - Skip confirmation prompt

**Examples:**
```bash
# With confirmation
agilemonitor remove 1

# Skip confirmation
agilemonitor remove 1 --yes
```

#### `agilemonitor pause <id>`
Pause monitoring for a site

```bash
agilemonitor pause 1
```

#### `agilemonitor resume <id>`
Resume monitoring for a site

```bash
agilemonitor resume 1
```

---

### Monitoring Data

#### `agilemonitor checks <id> [options]`
Get recent check history for a monitor

**Options:**
- `-l, --limit <number>` - Number of checks to show (default: 10)

**Examples:**
```bash
# Show last 10 checks
agilemonitor checks 1

# Show last 20 checks
agilemonitor checks 1 --limit 20
```

#### `agilemonitor alerts [options]`
List recent alerts

**Options:**
- `-u, --unresolved` - Show only unresolved alerts

**Examples:**
```bash
# Show all alerts
agilemonitor alerts

# Show only unresolved
agilemonitor alerts --unresolved
```

---

### Help & Info

#### `agilemonitor --help`
Show help for all commands

```bash
agilemonitor --help
```

#### `agilemonitor <command> --help`
Show help for specific command

```bash
agilemonitor add --help
```

#### `agilemonitor --version`
Show CLI version

```bash
agilemonitor --version
```

---

## Command Aliases

For faster typing, you can use these shortcuts:

```bash
agilemonitor list   # or: agilemonitor ls
agilemonitor remove # or: agilemonitor rm
am                  # same as: agilemonitor
```

**Examples:**
```bash
am ls
am add https://mysite.com
am rm 1 -y
```

---

## Configuration

The CLI stores your API key securely in your home directory:

- **Mac/Linux**: `~/.agilemonitor/config.json`
- **Windows**: `C:\Users\YourName\.agilemonitor\config.json`

This file is automatically created when you run `agilemonitor login`.

---

## Environment Variables

### `AGILEMONITOR_API`
Override the API base URL (for testing or self-hosted instances)

```bash
export AGILEMONITOR_API=https://your-api.com/api
agilemonitor list
```

---

## Examples

### Quick Monitor Setup

```bash
# Login
agilemonitor login am_live_abc123xyz

# Add multiple monitors
agilemonitor add https://mysite.com --name "Main Site"
agilemonitor add https://api.mysite.com --name "API" --interval 60
agilemonitor add https://blog.mysite.com --name "Blog"

# Check status
agilemonitor list
```

### Monitoring Workflow

```bash
# Check overall status
agilemonitor list

# Get details for specific monitor
agilemonitor status 1

# View recent checks
agilemonitor checks 1 --limit 20

# Check for alerts
agilemonitor alerts --unresolved
```

### Batch Operations

```bash
# Add monitors from a script
#!/bin/bash
sites=(
  "https://site1.com"
  "https://site2.com"
  "https://site3.com"
)

for site in "${sites[@]}"; do
  agilemonitor add "$site"
done
```

---

## Output Examples

### `agilemonitor list`

```
📊 Your Monitors (3)

● Main Site (ID: 1)
   URL: https://mysite.com
   Status: UP
   Interval: 300s
   Last Check: 2 minutes ago

● Production API (ID: 2)
   URL: https://api.mysite.com
   Status: UP
   Interval: 60s
   Last Check: 30 seconds ago

○ Test Site (ID: 3)
   URL: https://test.mysite.com
   Status: DOWN
   Interval: 300s
   Last Check: 5 minutes ago
```

### `agilemonitor checks 1`

```
📊 Recent Checks (Last 5)

✓ 2025-01-29 14:23:15
   Status: UP
   Response Time: 234ms
   Status Code: 200

✓ 2025-01-29 14:18:15
   Status: UP
   Response Time: 189ms
   Status Code: 200

✗ 2025-01-29 14:13:15
   Status: DOWN
   Response Time: 5000ms
   Message: Connection timeout
```

---

## Troubleshooting

### "Not logged in" error

**Problem**: You see `❌ Not logged in`

**Solution**: Run `agilemonitor login <your-api-key>`

---

### "Invalid API key format" error

**Problem**: API key doesn't start with `am_live_`

**Solution**: Get a new API key from https://agilemonitor.net/api-keys

---

### "API access requires PRO or TEAM plan" error

**Problem**: Your account doesn't have API access

**Solution**: Upgrade to PRO plan at https://agilemonitor.net/pricing

---

### "No response from server" error

**Problem**: Can't connect to API

**Solutions**:
1. Check your internet connection
2. Check if https://agilemonitor.net is accessible
3. Try again in a few moments

---

### Configuration file location

**Find your config file**:

Mac/Linux:
```bash
cat ~/.agilemonitor/config.json
```

Windows:
```cmd
type %USERPROFILE%\.agilemonitor\config.json
```

---

## Development

### Setup

```bash
git clone https://github.com/yourusername/agilemonitor-cli.git
cd agilemonitor-cli
npm install
```

### Testing Locally

```bash
# Link for local testing
npm link

# Now you can run:
agilemonitor --help
```

### Making Changes

```bash
# Edit files
vim cli.js

# Test
agilemonitor list

# Unlink when done
npm unlink -g
```

---

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## Support

- **Documentation**: https://agilemonitor.net/docs
- **API Reference**: https://agilemonitor.net/api-docs
- **Issues**: https://github.com/yourusername/agilemonitor-cli/issues
- **Email**: support@agilemonitor.net

---

## License

MIT © AgileMonitor

---

## Related Projects

- **AgileMonitor Web**: https://agilemonitor.net
- **AgileMonitor API**: https://agilemonitor.net/api-docs
- **AgileMonitor Status**: https://status.agilemonitor.net

---

## Changelog

### v1.0.0 (2025-01-29)

- ✨ Initial release
- ✅ Authentication commands (`login`, `logout`, `whoami`)
- ✅ Monitor management (`add`, `list`, `status`, `remove`)
- ✅ Check history (`checks`)
- ✅ Alert viewing (`alerts`)
- ✅ Pause/resume monitoring
- ✅ Beautiful colored output
- ✅ Progress spinners
- ✅ Secure API key storage

---

**Made with ❤️ by the AgileMonitor team**