From c7362f3adae56489616c21d13a8d45067fc9d88e Mon Sep 17 00:00:00 2001 From: Nawaz Dhandala Date: Sun, 15 Feb 2026 20:10:21 +0000 Subject: [PATCH] feat: add comprehensive CLI documentation including authentication, command reference, resource operations, output formats, and scripting for automation --- Docs/Content/cli/authentication.md | 155 ++++++++++++++++ Docs/Content/cli/command-reference.md | 233 ++++++++++++++++++++++++ Docs/Content/cli/index.md | 68 +++++++ Docs/Content/cli/output-formats.md | 80 ++++++++ Docs/Content/cli/resource-operations.md | 219 ++++++++++++++++++++++ Docs/Content/cli/scripting.md | 149 +++++++++++++++ 6 files changed, 904 insertions(+) create mode 100644 Docs/Content/cli/authentication.md create mode 100644 Docs/Content/cli/command-reference.md create mode 100644 Docs/Content/cli/index.md create mode 100644 Docs/Content/cli/output-formats.md create mode 100644 Docs/Content/cli/resource-operations.md create mode 100644 Docs/Content/cli/scripting.md diff --git a/Docs/Content/cli/authentication.md b/Docs/Content/cli/authentication.md new file mode 100644 index 0000000000..6fa246a8bd --- /dev/null +++ b/Docs/Content/cli/authentication.md @@ -0,0 +1,155 @@ +# Authentication + +The OneUptime CLI supports multiple ways to authenticate with your OneUptime instance. You can use named contexts, environment variables, or pass credentials directly as flags. + +## Login + +Authenticate with your OneUptime instance using an API key: + +```bash +oneuptime login +``` + +**Arguments:** + +| Argument | Description | +|----------|-------------| +| `` | Your OneUptime API key (e.g., `sk-your-api-key`) | +| `` | Your OneUptime instance URL (e.g., `https://oneuptime.com`) | + +**Options:** + +| Option | Description | +|--------|-------------| +| `--context-name ` | Name for this context (default: `"default"`) | + +**Examples:** + +```bash +# Login with default context +oneuptime login sk-abc123 https://oneuptime.com + +# Login with a named context +oneuptime login sk-abc123 https://oneuptime.com --context-name production + +# Set up multiple environments +oneuptime login sk-prod-key https://oneuptime.com --context-name production +oneuptime login sk-staging-key https://staging.oneuptime.com --context-name staging +``` + +## Contexts + +Contexts allow you to save and switch between multiple OneUptime environments (e.g., production, staging, development). + +### List Contexts + +```bash +oneuptime context list +``` + +Displays all configured contexts. The current context is marked with `*`. + +### Switch Context + +```bash +oneuptime context use +``` + +Switch to a different named context for all subsequent commands. + +```bash +# Switch to staging +oneuptime context use staging + +# Switch to production +oneuptime context use production +``` + +### View Current Context + +```bash +oneuptime context current +``` + +Displays the currently active context, including the instance URL and a masked API key. + +### Delete a Context + +```bash +oneuptime context delete +``` + +Remove a named context. If the deleted context is the current one, the CLI automatically switches to the first remaining context. + +## Credential Resolution + +Credentials are resolved in the following priority order: + +1. **CLI flags** (`--api-key` and `--url`) +2. **Environment variables** (`ONEUPTIME_API_KEY` and `ONEUPTIME_URL`) +3. **Named context** (via `--context` flag) +4. **Current context** (from saved configuration) + +You can mix sources -- for example, use an environment variable for the API key and a saved context for the URL. + +### Using CLI Flags + +```bash +oneuptime --api-key sk-abc123 --url https://oneuptime.com incident list +``` + +### Using Environment Variables + +```bash +export ONEUPTIME_API_KEY=sk-abc123 +export ONEUPTIME_URL=https://oneuptime.com + +oneuptime incident list +``` + +### Using a Specific Context + +```bash +oneuptime --context production incident list +``` + +## Verify Authentication + +Check your current authentication status: + +```bash +oneuptime whoami +``` + +This displays: +- Instance URL +- Masked API key +- Current context name + +If not authenticated, the command shows a helpful message suggesting you run `oneuptime login`. + +## Configuration File + +Credentials are stored in `~/.oneuptime/config.json` with restricted permissions (`0600`). + +```json +{ + "currentContext": "production", + "contexts": { + "production": { + "name": "production", + "apiUrl": "https://oneuptime.com", + "apiKey": "sk-..." + }, + "staging": { + "name": "staging", + "apiUrl": "https://staging.oneuptime.com", + "apiKey": "sk-..." + } + }, + "defaults": { + "output": "table", + "limit": 10 + } +} +``` diff --git a/Docs/Content/cli/command-reference.md b/Docs/Content/cli/command-reference.md new file mode 100644 index 0000000000..ffb2cd7bb6 --- /dev/null +++ b/Docs/Content/cli/command-reference.md @@ -0,0 +1,233 @@ +# Command Reference + +Complete reference for all OneUptime CLI commands. + +## Authentication Commands + +### `oneuptime login` + +Authenticate with a OneUptime instance. + +```bash +oneuptime login [--context-name ] +``` + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `` | argument | Yes | API key for authentication | +| `` | argument | Yes | OneUptime instance URL | +| `--context-name` | option | No | Context name (default: `"default"`) | + +--- + +### `oneuptime context list` + +List all saved contexts. + +```bash +oneuptime context list +``` + +--- + +### `oneuptime context use` + +Switch to a named context. + +```bash +oneuptime context use +``` + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `` | argument | Yes | Context name to activate | + +--- + +### `oneuptime context current` + +Display the active context with masked API key. + +```bash +oneuptime context current +``` + +--- + +### `oneuptime context delete` + +Remove a saved context. + +```bash +oneuptime context delete +``` + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `` | argument | Yes | Context name to delete | + +--- + +## Resource Commands + +All resource commands follow the same pattern. Replace `` with any supported resource name (e.g., `incident`, `monitor`, `alert`, `status-page`). + +### `oneuptime list` + +List resources with filtering and pagination. + +```bash +oneuptime list [options] +``` + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `--query ` | string | None | Filter criteria as JSON | +| `--limit ` | number | `10` | Maximum results | +| `--skip ` | number | `0` | Results to skip | +| `--sort ` | string | None | Sort order as JSON | +| `-o, --output` | string | `table` | Output format | + +--- + +### `oneuptime get` + +Get a single resource by ID. + +```bash +oneuptime get [-o ] +``` + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `` | argument | Yes | Resource ID (UUID) | +| `-o, --output` | option | No | Output format | + +--- + +### `oneuptime create` + +Create a new resource. + +```bash +oneuptime create [--data | --file ] [-o ] +``` + +| Option | Type | Required | Description | +|--------|------|----------|-------------| +| `--data ` | string | One of `--data` or `--file` | Resource data as JSON | +| `--file ` | string | One of `--data` or `--file` | Path to JSON file | +| `-o, --output` | string | No | Output format | + +--- + +### `oneuptime update` + +Update an existing resource. + +```bash +oneuptime update --data [-o ] +``` + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `` | argument | Yes | Resource ID | +| `--data ` | option | Yes | Fields to update as JSON | +| `-o, --output` | option | No | Output format | + +--- + +### `oneuptime delete` + +Delete a resource. + +```bash +oneuptime delete +``` + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `` | argument | Yes | Resource ID | + +--- + +### `oneuptime count` + +Count resources matching a filter. + +```bash +oneuptime count [--query ] +``` + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `--query ` | string | None | Filter criteria as JSON | + +--- + +## Utility Commands + +### `oneuptime version` + +Display the CLI version. + +```bash +oneuptime version +``` + +--- + +### `oneuptime whoami` + +Show current authentication details. + +```bash +oneuptime whoami +``` + +Displays the instance URL, masked API key, and context name. + +--- + +### `oneuptime resources` + +List all available resource types. + +```bash +oneuptime resources [--type ] +``` + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `--type ` | string | None | Filter by `database` or `analytics` | + +--- + +## Global Options + +These flags are available on all commands: + +| Option | Description | +|--------|-------------| +| `--api-key ` | Override API key | +| `--url ` | Override instance URL | +| `--context ` | Use a specific context | +| `-o, --output ` | Output format: `json`, `table`, `wide` | +| `--no-color` | Disable colored output | +| `--help` | Show help | +| `--version` | Show version | + +## API Routes + +For reference, the CLI maps commands to these API endpoints: + +| Command | Method | Endpoint | +|---------|--------|----------| +| `list` | POST | `/api//get-list` | +| `get` | POST | `/api///get-item` | +| `create` | POST | `/api/` | +| `update` | PUT | `/api///` | +| `delete` | DELETE | `/api///` | +| `count` | POST | `/api//count` | + +All requests include the `APIKey` header for authentication. diff --git a/Docs/Content/cli/index.md b/Docs/Content/cli/index.md new file mode 100644 index 0000000000..8914a133e9 --- /dev/null +++ b/Docs/Content/cli/index.md @@ -0,0 +1,68 @@ +# OneUptime CLI + +The OneUptime CLI is a command-line interface for managing your OneUptime resources directly from the terminal. It supports full CRUD operations on monitors, incidents, alerts, status pages, and more. + +## Features + +- **Multi-environment support** with named contexts for production, staging, and development +- **Auto-discovery** of available resources from your OneUptime instance +- **Flexible authentication** via CLI flags, environment variables, or saved contexts +- **Smart output formatting** with JSON, table, and wide display modes +- **Scriptable** for CI/CD pipelines and automation workflows + +## Installation + +```bash +npm install -g @oneuptime/cli +``` + +## Quick Start + +```bash +# Authenticate with your OneUptime instance +oneuptime login https://oneuptime.com + +# List your monitors +oneuptime monitor list + +# View a specific incident +oneuptime incident get + +# See all available resources +oneuptime resources +``` + +## Documentation + +| Guide | Description | +|-------|-------------| +| [Authentication](./authentication.md) | Login, contexts, and credential management | +| [Resource Operations](./resource-operations.md) | CRUD operations on monitors, incidents, alerts, and more | +| [Output Formats](./output-formats.md) | JSON, table, and wide output modes | +| [Scripting and CI/CD](./scripting.md) | Automation, environment variables, and pipeline usage | +| [Command Reference](./command-reference.md) | Complete reference for all commands and options | + +## Global Options + +These flags can be used with any command: + +| Flag | Description | +|------|-------------| +| `--api-key ` | Override API key for this command | +| `--url ` | Override instance URL for this command | +| `--context ` | Use a specific named context | +| `-o, --output ` | Output format: `json`, `table`, `wide` | +| `--no-color` | Disable colored output | +| `--help` | Show command help | +| `--version` | Show CLI version | + +## Getting Help + +```bash +# General help +oneuptime --help + +# Help for a specific command +oneuptime monitor --help +oneuptime monitor list --help +``` diff --git a/Docs/Content/cli/output-formats.md b/Docs/Content/cli/output-formats.md new file mode 100644 index 0000000000..8798bcaee3 --- /dev/null +++ b/Docs/Content/cli/output-formats.md @@ -0,0 +1,80 @@ +# Output Formats + +The OneUptime CLI supports three output formats: **table**, **JSON**, and **wide**. You can set the format with the `-o` or `--output` flag on any command. + +## Table (Default) + +The default format when running in an interactive terminal. Displays results as an ASCII table with intelligently selected columns. + +```bash +oneuptime incident list +``` + +``` +┌──────────────────┬───────────────────────┬────────────┬─────────────────────┐ +│ _id │ title │ status │ createdAt │ +├──────────────────┼───────────────────────┼────────────┼─────────────────────┤ +│ abc-123 │ API Outage │ active │ 2025-01-15T10:30:00 │ +│ def-456 │ Database Slowdown │ resolved │ 2025-01-14T08:15:00 │ +└──────────────────┴───────────────────────┴────────────┴─────────────────────┘ +``` + +Table format behavior: +- Selects up to 6 columns, prioritizing: `_id`, `name`, `title`, `status`, `createdAt`, `updatedAt` +- Truncates values longer than 60 characters with `...` +- Uses color-coded headers (disable with `--no-color`) + +## JSON + +Raw JSON output, pretty-printed with 2-space indentation. This is the best format for scripting and piping to other tools. + +```bash +oneuptime incident list -o json +``` + +```json +[ + { + "_id": "abc-123", + "title": "API Outage", + "status": "active", + "createdAt": "2025-01-15T10:30:00Z" + } +] +``` + +JSON format is automatically used when the output is piped to another command (non-TTY mode): + +```bash +# JSON is used automatically when piping +oneuptime incident list | jq '.[].title' +``` + +## Wide + +Displays all columns without truncation. Useful for detailed inspection but may produce very wide output. + +```bash +oneuptime incident list -o wide +``` + +## Disabling Color + +Color output can be disabled in several ways: + +```bash +# Using the --no-color flag +oneuptime --no-color incident list + +# Using the NO_COLOR environment variable +NO_COLOR=1 oneuptime incident list +``` + +## Special Output Cases + +| Scenario | Output | +|----------|--------| +| Empty result set | `"No results found."` | +| No data returned | `"No data returned."` | +| Single object (e.g., `get`) | Key-value table format | +| `count` command | Plain numeric value | diff --git a/Docs/Content/cli/resource-operations.md b/Docs/Content/cli/resource-operations.md new file mode 100644 index 0000000000..9b83ccddae --- /dev/null +++ b/Docs/Content/cli/resource-operations.md @@ -0,0 +1,219 @@ +# Resource Operations + +The OneUptime CLI provides full CRUD (Create, Read, Update, Delete) operations for all supported resources. Resources are auto-discovered from your OneUptime instance. + +## Available Resources + +Run the following command to see all available resource types: + +```bash +oneuptime resources +``` + +You can filter by type: + +```bash +# Show only database resources +oneuptime resources --type database + +# Show only analytics resources +oneuptime resources --type analytics +``` + +Common resources include: + +| Resource | Command | +|----------|---------| +| Incident | `oneuptime incident` | +| Alert | `oneuptime alert` | +| Monitor | `oneuptime monitor` | +| Monitor Status | `oneuptime monitor-status` | +| Incident State | `oneuptime incident-state` | +| Status Page | `oneuptime status-page` | +| On-Call Policy | `oneuptime on-call-policy` | +| Team | `oneuptime team` | +| Scheduled Maintenance Event | `oneuptime scheduled-maintenance-event` | + +## List Resources + +Retrieve a list of resources with optional filtering, pagination, and sorting. + +```bash +oneuptime list [options] +``` + +**Options:** + +| Option | Description | Default | +|--------|-------------|---------| +| `--query ` | Filter criteria as JSON | None | +| `--limit ` | Maximum number of results | `10` | +| `--skip ` | Number of results to skip | `0` | +| `--sort ` | Sort order as JSON | None | +| `-o, --output ` | Output format | `table` | + +**Examples:** + +```bash +# List the 10 most recent incidents +oneuptime incident list + +# List active incidents +oneuptime incident list --query '{"status":"active"}' + +# List with pagination +oneuptime incident list --limit 20 --skip 40 + +# Sort by creation date (descending) +oneuptime incident list --sort '{"createdAt":-1}' + +# Output as JSON +oneuptime incident list -o json +``` + +## Get a Resource + +Retrieve a single resource by its ID. + +```bash +oneuptime get +``` + +**Arguments:** + +| Argument | Description | +|----------|-------------| +| `` | The resource ID (UUID) | + +**Examples:** + +```bash +# Get a specific incident +oneuptime incident get 550e8400-e29b-41d4-a716-446655440000 + +# Get a monitor as JSON +oneuptime monitor get abc-123 -o json +``` + +## Create a Resource + +Create a new resource from inline JSON or a file. + +```bash +oneuptime create [options] +``` + +**Options:** + +| Option | Description | +|--------|-------------| +| `--data ` | Resource data as a JSON object | +| `--file ` | Path to a JSON file containing resource data | +| `-o, --output ` | Output format | + +You must provide either `--data` or `--file`. + +**Examples:** + +```bash +# Create a monitor with inline JSON +oneuptime monitor create --data '{"name":"API Health Check","projectId":"your-project-id"}' + +# Create from a JSON file +oneuptime monitor create --file monitor.json + +# Create and output as JSON to capture the ID +oneuptime monitor create --data '{"name":"New Monitor"}' -o json +``` + +## Update a Resource + +Update an existing resource by ID. + +```bash +oneuptime update [options] +``` + +**Arguments:** + +| Argument | Description | +|----------|-------------| +| `` | The resource ID | + +**Options:** + +| Option | Description | +|--------|-------------| +| `--data ` | Fields to update as JSON (required) | +| `-o, --output ` | Output format | + +**Examples:** + +```bash +# Resolve an incident +oneuptime incident update abc-123 --data '{"status":"resolved"}' + +# Rename a monitor +oneuptime monitor update abc-123 --data '{"name":"Updated Monitor Name"}' +``` + +## Delete a Resource + +Delete a resource by ID. + +```bash +oneuptime delete +``` + +**Arguments:** + +| Argument | Description | +|----------|-------------| +| `` | The resource ID | + +**Examples:** + +```bash +oneuptime incident delete abc-123 +oneuptime monitor delete 550e8400-e29b-41d4-a716-446655440000 +``` + +## Count Resources + +Count resources matching optional filter criteria. + +```bash +oneuptime count [options] +``` + +**Options:** + +| Option | Description | +|--------|-------------| +| `--query ` | Filter criteria as JSON | + +**Examples:** + +```bash +# Count all incidents +oneuptime incident count + +# Count active incidents +oneuptime incident count --query '{"status":"active"}' + +# Count monitors +oneuptime monitor count +``` + +## Analytics Resources + +Analytics resources (e.g., logs, traces) support a limited set of operations: + +| Operation | Supported | +|-----------|-----------| +| `list` | Yes | +| `create` | Yes | +| `count` | Yes | +| `get` | No | +| `update` | No | +| `delete` | No | diff --git a/Docs/Content/cli/scripting.md b/Docs/Content/cli/scripting.md new file mode 100644 index 0000000000..298d5ac683 --- /dev/null +++ b/Docs/Content/cli/scripting.md @@ -0,0 +1,149 @@ +# Scripting and CI/CD + +The OneUptime CLI is designed for automation. It supports environment-variable-based authentication, JSON output for programmatic parsing, and appropriate exit codes for pipeline integration. + +## Environment Variables + +Set these environment variables to authenticate without saved contexts: + +```bash +export ONEUPTIME_API_KEY=sk-your-api-key +export ONEUPTIME_URL=https://oneuptime.com +``` + +These take precedence over saved contexts but are overridden by CLI flags. + +## Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Success | +| `1` | General error | +| `2` | Authentication error (missing or invalid credentials) | +| `3` | Not found (404) | + +Use exit codes in scripts to handle errors: + +```bash +if ! oneuptime monitor list > /dev/null 2>&1; then + echo "Failed to list monitors" + exit 1 +fi +``` + +## JSON Processing with jq + +Use `-o json` to produce machine-readable output: + +```bash +# Extract all incident titles +oneuptime incident list -o json | jq '.[].title' + +# Get the ID of a newly created monitor +NEW_ID=$(oneuptime monitor create --data '{"name":"API Health"}' -o json | jq -r '._id') +echo "Created monitor: $NEW_ID" + +# Count incidents matching a filter +oneuptime incident count --query '{"status":"active"}' +``` + +## Creating Resources from Files + +Use `--file` to create resources from JSON files, useful for version-controlled infrastructure: + +```bash +# monitor.json +# { +# "name": "API Health Check", +# "projectId": "your-project-id" +# } + +oneuptime monitor create --file monitor.json +``` + +## Batch Operations + +Process multiple resources in a loop: + +```bash +# Create multiple monitors from a JSON array file +cat monitors.json | jq -r '.[] | @json' | while read monitor; do + oneuptime monitor create --data "$monitor" +done +``` + +## CI/CD Pipeline Examples + +### GitHub Actions + +```yaml +name: Check Service Health +on: + schedule: + - cron: '*/5 * * * *' + +jobs: + health-check: + runs-on: ubuntu-latest + steps: + - name: Install OneUptime CLI + run: npm install -g @oneuptime/cli + + - name: Check for down monitors + env: + ONEUPTIME_API_KEY: ${{ secrets.ONEUPTIME_API_KEY }} + ONEUPTIME_URL: https://oneuptime.com + run: | + DOWN_COUNT=$(oneuptime monitor count --query '{"status":"down"}') + if [ "$DOWN_COUNT" -gt 0 ]; then + echo "WARNING: $DOWN_COUNT monitors are down" + exit 1 + fi +``` + +### Generic CI/CD Script + +```bash +#!/bin/bash +set -e + +export ONEUPTIME_API_KEY="$CI_ONEUPTIME_API_KEY" +export ONEUPTIME_URL="$CI_ONEUPTIME_URL" + +# Create a deployment incident +oneuptime incident create --data '{ + "title": "Deployment Started", + "status": "investigating" +}' + +# Run deployment steps here... + +# Resolve the incident after successful deployment +oneuptime incident update "$INCIDENT_ID" --data '{"status":"resolved"}' +``` + +### Docker + +```dockerfile +FROM node:20-slim +RUN npm install -g @oneuptime/cli +ENV ONEUPTIME_API_KEY="" +ENV ONEUPTIME_URL="" +ENTRYPOINT ["oneuptime"] +``` + +```bash +docker run --rm \ + -e ONEUPTIME_API_KEY=sk-abc123 \ + -e ONEUPTIME_URL=https://oneuptime.com \ + oneuptime-cli incident list +``` + +## Using a Specific Context in Scripts + +If you have multiple contexts saved, target a specific one: + +```bash +oneuptime --context production incident list +oneuptime --context staging monitor count +```