mirror of
https://github.com/OneUptime/oneuptime.git
synced 2026-04-06 00:32:12 +02:00
feat: add comprehensive CLI documentation including authentication, command reference, resource operations, output formats, and scripting for automation
This commit is contained in:
Nawaz Dhandala
155
Docs/Content/cli/authentication.md
Normal file
155
Docs/Content/cli/authentication.md
Normal file
@@ -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 <api-key> <instance-url>
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
|
||||
| Argument | Description |
|
||||
|----------|-------------|
|
||||
| `<api-key>` | Your OneUptime API key (e.g., `sk-your-api-key`) |
|
||||
| `<instance-url>` | Your OneUptime instance URL (e.g., `https://oneuptime.com`) |
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--context-name <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 <name>
|
||||
```
|
||||
|
||||
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 <name>
|
||||
```
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
```
|
||||
233
Docs/Content/cli/command-reference.md
Normal file
233
Docs/Content/cli/command-reference.md
Normal file
@@ -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 <api-key> <instance-url> [--context-name <name>]
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `<api-key>` | argument | Yes | API key for authentication |
|
||||
| `<instance-url>` | 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 <name>
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `<name>` | 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 <name>
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `<name>` | argument | Yes | Context name to delete |
|
||||
|
||||
---
|
||||
|
||||
## Resource Commands
|
||||
|
||||
All resource commands follow the same pattern. Replace `<resource>` with any supported resource name (e.g., `incident`, `monitor`, `alert`, `status-page`).
|
||||
|
||||
### `oneuptime <resource> list`
|
||||
|
||||
List resources with filtering and pagination.
|
||||
|
||||
```bash
|
||||
oneuptime <resource> list [options]
|
||||
```
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `--query <json>` | string | None | Filter criteria as JSON |
|
||||
| `--limit <n>` | number | `10` | Maximum results |
|
||||
| `--skip <n>` | number | `0` | Results to skip |
|
||||
| `--sort <json>` | string | None | Sort order as JSON |
|
||||
| `-o, --output` | string | `table` | Output format |
|
||||
|
||||
---
|
||||
|
||||
### `oneuptime <resource> get`
|
||||
|
||||
Get a single resource by ID.
|
||||
|
||||
```bash
|
||||
oneuptime <resource> get <id> [-o <format>]
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `<id>` | argument | Yes | Resource ID (UUID) |
|
||||
| `-o, --output` | option | No | Output format |
|
||||
|
||||
---
|
||||
|
||||
### `oneuptime <resource> create`
|
||||
|
||||
Create a new resource.
|
||||
|
||||
```bash
|
||||
oneuptime <resource> create [--data <json> | --file <path>] [-o <format>]
|
||||
```
|
||||
|
||||
| Option | Type | Required | Description |
|
||||
|--------|------|----------|-------------|
|
||||
| `--data <json>` | string | One of `--data` or `--file` | Resource data as JSON |
|
||||
| `--file <path>` | string | One of `--data` or `--file` | Path to JSON file |
|
||||
| `-o, --output` | string | No | Output format |
|
||||
|
||||
---
|
||||
|
||||
### `oneuptime <resource> update`
|
||||
|
||||
Update an existing resource.
|
||||
|
||||
```bash
|
||||
oneuptime <resource> update <id> --data <json> [-o <format>]
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `<id>` | argument | Yes | Resource ID |
|
||||
| `--data <json>` | option | Yes | Fields to update as JSON |
|
||||
| `-o, --output` | option | No | Output format |
|
||||
|
||||
---
|
||||
|
||||
### `oneuptime <resource> delete`
|
||||
|
||||
Delete a resource.
|
||||
|
||||
```bash
|
||||
oneuptime <resource> delete <id>
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `<id>` | argument | Yes | Resource ID |
|
||||
|
||||
---
|
||||
|
||||
### `oneuptime <resource> count`
|
||||
|
||||
Count resources matching a filter.
|
||||
|
||||
```bash
|
||||
oneuptime <resource> count [--query <json>]
|
||||
```
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `--query <json>` | 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 <type>]
|
||||
```
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `--type <type>` | string | None | Filter by `database` or `analytics` |
|
||||
|
||||
---
|
||||
|
||||
## Global Options
|
||||
|
||||
These flags are available on all commands:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--api-key <key>` | Override API key |
|
||||
| `--url <url>` | Override instance URL |
|
||||
| `--context <name>` | Use a specific context |
|
||||
| `-o, --output <format>` | 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/<resource>/get-list` |
|
||||
| `get` | POST | `/api/<resource>/<id>/get-item` |
|
||||
| `create` | POST | `/api/<resource>` |
|
||||
| `update` | PUT | `/api/<resource>/<id>/` |
|
||||
| `delete` | DELETE | `/api/<resource>/<id>/` |
|
||||
| `count` | POST | `/api/<resource>/count` |
|
||||
|
||||
All requests include the `APIKey` header for authentication.
|
||||
68
Docs/Content/cli/index.md
Normal file
68
Docs/Content/cli/index.md
Normal file
@@ -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 <your-api-key> https://oneuptime.com
|
||||
|
||||
# List your monitors
|
||||
oneuptime monitor list
|
||||
|
||||
# View a specific incident
|
||||
oneuptime incident get <incident-id>
|
||||
|
||||
# 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 <key>` | Override API key for this command |
|
||||
| `--url <url>` | Override instance URL for this command |
|
||||
| `--context <name>` | Use a specific named context |
|
||||
| `-o, --output <format>` | 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
|
||||
```
|
||||
80
Docs/Content/cli/output-formats.md
Normal file
80
Docs/Content/cli/output-formats.md
Normal file
@@ -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 |
|
||||
219
Docs/Content/cli/resource-operations.md
Normal file
219
Docs/Content/cli/resource-operations.md
Normal file
@@ -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 <resource> list [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--query <json>` | Filter criteria as JSON | None |
|
||||
| `--limit <n>` | Maximum number of results | `10` |
|
||||
| `--skip <n>` | Number of results to skip | `0` |
|
||||
| `--sort <json>` | Sort order as JSON | None |
|
||||
| `-o, --output <format>` | 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 <resource> get <id>
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
|
||||
| Argument | Description |
|
||||
|----------|-------------|
|
||||
| `<id>` | 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 <resource> create [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--data <json>` | Resource data as a JSON object |
|
||||
| `--file <path>` | Path to a JSON file containing resource data |
|
||||
| `-o, --output <format>` | 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 <resource> update <id> [options]
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
|
||||
| Argument | Description |
|
||||
|----------|-------------|
|
||||
| `<id>` | The resource ID |
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--data <json>` | Fields to update as JSON (required) |
|
||||
| `-o, --output <format>` | 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 <resource> delete <id>
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
|
||||
| Argument | Description |
|
||||
|----------|-------------|
|
||||
| `<id>` | 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 <resource> count [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--query <json>` | 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 |
|
||||
149
Docs/Content/cli/scripting.md
Normal file
149
Docs/Content/cli/scripting.md
Normal file
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user