# Xitoring CLI

Xitoring CLI is a Node.js command-line interface (CLI) tool for interacting with [Xitoring](https://xitoring.com/)'s services.

It works on **Windows**, **macOS**, and **Linux**.

---

## Installation

```bash
npm install -g xitoring-cli
```

This installs the `xitoring-cli` tool globally. After installation, you can run it using:

```bash
xitoring
```

More information can be found on [npmjs.com](https://www.npmjs.com/package/xitoring-cli).

---

## Requirements

A [Xitoring account](https://app.xitoring.com/ui) is required to use the CLI.

---

## Getting Started

1. Install `xitoring-cli` using npm (or any package manager).
2. Authenticate with your Xitoring account:

```bash
   xitoring login
   ```

This provides a browser link to log in and obtain an API key.
3. Start using commands to interact with your account.

---

## Commands

### Authentication

- **Login**

```bash
   xitoring login
   ```

Log in to your account and store your API key.

- **General Help**

```bash
   xitoring help
   ```

Show available commands and usage.

---

### Servers

- **List Servers**

```bash
   xitoring servers
   ```

Display all servers and their metric data.

- **Examples with Flags**

```bash
   # Show only selected columns
   xitoring servers --columns=OS,Label,CPU,Memory

# Sort by CPU usage
   xitoring servers --sort=CPU

# Filter by OS
   xitoring servers --os=linux

# Filter by group
   xitoring servers --groups=Production
   ```

- **Available Flags**

```text
   --sort      : sort table by (CPU, Memory, OS, Label)
   --columns   : customize table columns by (OS, Label, Checks, CPU, Memory, IO read, IO write, Group)
   --groups    : filter by group name
   --os        : filter by OS (linux, windows)
   ```

---

### Uptime

- **List Uptime Checks**

```bash
   xitoring uptime
   ```

Display all uptime and heartbeat checks with their real-time status.

- **Examples with Flags**

```bash
   # Show only selected columns
   xitoring uptime --columns=Status,Label,Type,Host

# Sort by uptime
   xitoring uptime --sort=Uptime

# Filter by status
   xitoring uptime --status=down

# Filter by check type
   xitoring uptime --type=http

# Filter by period
   xitoring uptime --period=this_month
   ```

- **Available Flags**

```text
   --sort      : sort table by (Uptime, Label)
   --columns   : customize table columns by (Status, Type, Label, Group, Host, Uptime)
   --groups    : filter by group name
   --status    : filter by status (up, down, pause, maintenance)
   --period    : filter by period (today, this_week, this_month, last_month, this_year)
   --type      : filter by check type (ping, http, ...)
   ```

---

### SSL

- **List SSL Endpoints**

```bash
   xitoring ssl
   ```

Display all SSL endpoints and their certificate status.

- **Examples with Flags**

```bash
   # Show only selected columns
   # Note: If your column names contain spaces (e.g., "Remaining Days"), wrap them in quotes.
   xitoring ssl --columns=Status,Label,Host,Port,Issuer,Grade

# Sort by expiry
   xitoring ssl --sort=Expire

# Filter by expire (e.g., expiring within 30 days)
   xitoring ssl --expire=30

# Filter by group
   xitoring ssl --groups=Websites
   ```

- **Available Flags**

```text
   --sort      : sort table by (Expire, Label)
   --columns   : customize table columns by (Status, Label, Host, Port, Issuer, Group, Grade, Remaining Days)
   --groups    : filter by group name
   --expire    : filter by expire
   ```

---

## Help Output Reference

For detailed filter options and usage, you can run the contextual help for each section:

```text
xitoring help --servers

Usage: xitoring servers <flags>

--sort    : sort table by (CPU , Memory , OS , Label)
     --columns : customize table columns by (OS , Label , Checks , CPU , Memory , IO read , IO write , Group)
     --groups  : filter by group name
     --os      : filter by os (linux , windows)
```

```text
xitoring help --uptime

Usage: xitoring uptime <flags>

--sort    : sort table by (Uptime , Label)
     --columns : customize table columns by (Status , Type , Label , Group , Host , Uptime)
     --groups  : filter by group name
     --status  : filter by status (up , down , pause , maintenance)
     --period  : filter by period (today , this_week , this_month , last_month , this_year)
     --type    : filter by check type (ping , http , ...)
```

```text
xitoring help --ssl

Usage: xitoring ssl <flags>

--sort    : sort table by (Expire , Label)
     --columns : customize table columns by (Status , Label , Host , Port , Issuer , Group , Grade , Remaining Days)
     --groups  : filter by group name
     --expire  : filter by expire
```

> **Tip:** Use equals-sign syntax with comma-separated values for flags that accept lists.
> Examples:
> 
> - `xitoring servers --columns=OS,Label,CPU,Memory`
> - `xitoring uptime --columns=Status,Label,Type,Host`

---

## Example Workflow

```bash
# Login
xitoring login

# List servers with selected columns
xitoring servers --columns=OS,Label,CPU,Memory

# Show uptime checks for HTTP only
xitoring uptime --type=http --columns=Status,Label,Host

# Show SSL endpoints expiring in less than 30 days
xitoring ssl --expire=30 --sort=Expire
```

---

## Revoking CLI Access

Currently, the Xitoring CLI does not include a direct `logout` command.

To remove access, you need to manually revoke the CLI API key from your Xitoring account:

1. Go to [Xitoring Account Settings](https://app.xitoring.com/ui/account).
2. Locate the **API Keys** section.
3. Delete the API key that was generated for your CLI session.

This will immediately revoke access for the CLI on your system.

---

## Notes

- Use `xitoring help` for a full list of commands.
- Use `xitoring help --servers`, `xitoring help --uptime`, and `xitoring help --ssl` to see available filters and options.
- Commands can be combined with flags for advanced filtering and customization.
- To log out, remove your API key from Xitoring [Account Settings](https://app.xitoring.com/ui/account).