CLI Reference

Overview

The Incident Management CLI (im) provides comprehensive command-line access to platform functionality. It’s designed for automation, scripting, and developers working with the incident management system.

CLI Status: All documented commands have been tested and work with the current implementation. The CLI communicates with the API server at http://localhost:8080 by default.

Core Capabilities:

✅ Complete incident lifecycle management
✅ Connector and integration configuration
✅ Real-time incident monitoring
✅ Comprehensive analytics and metrics
✅ Timeline export and reporting
✅ ChatOps integration management

Installation & Setup

Build from Source

The CLI is built as part of the main project:

# Clone and build project
git clone https://github.com/systmms/incidents.git
cd incidents

# Build all components including CLI
make build

# CLI binary will be at ./bin/im
./bin/im --help

# Optionally add to PATH for convenience
export PATH=$PATH:$(pwd)/bin

Development Status: Pre-built releases are not yet available. Build from source using the instructions above.

Configuration

Server Connection

The CLI requires the API server to be running and connects to http://localhost:8080 by default:

# Start server (required for most commands)
./bin/server

# Test connection
curl http://localhost:8080/health
# Expected: {"status":"healthy"}

# Use CLI with default server
./bin/im declare --title "Test incident" --sev SEV-2

Custom Server URL

Override the default server URL for commands:

# Use --api flag
./bin/im --api http://your-server:8080 declare --title "Remote incident"

# Or use --server flag (command-specific)
./bin/im connector list --server http://your-server:8080
./bin/im metrics overview --server http://your-server:8080

Development Note: The CLI currently connects directly to the server without API keys or complex configuration files. Authentication and configuration management features are planned for future releases.

Command Categories

All commands have been tested with the current implementation:

Core Incident Operations

declare - Create new incidents
ack - Acknowledge incidents
mitigate - Mark incidents as mitigated
resolve - Resolve incidents
close - Close resolved incidents

System Operations

serve - Start the web server
live - Stream live incident events

Integration Management

connector - Manage ITSM connectors (ServiceNow, Jira)
chatops - Manage ChatOps providers (Slack, Teams)

Analytics & Monitoring

metrics - View incident analytics
sla - SLA tracking operations
correlate - Correlation operations

Timeline & Reporting

timeline - Timeline operations and export

Utility Commands

completion - Generate shell completions
escalation - Manage escalation rules
help - Command help

Incident Management

Creating Incidents

The declare command creates new incidents:

# Basic incident declaration
./bin/im declare --title "Database connection timeout" --sev SEV-2

# With service information
./bin/im declare --title "API Gateway Down" --sev SEV-1 --service api

# With labels for additional metadata
./bin/im declare --title "Cache performance issue" --sev SEV-3 --labels env=prod,region=us-west

Available Flags:

--title (required) - Incident title
--sev - Severity level: SEV-1, SEV-2, SEV-3, SEV-4 (default: SEV-3)
--service - Affected service name
--labels - Additional metadata (key=value pairs)
--api - API server URL (default: http://localhost:8080)

Managing Incidents

Acknowledging Incidents

# Acknowledge an incident
./bin/im ack --incident INC-12345

# Acknowledge through a specific provider
./bin/im ack --incident INC-12345 --provider pagerduty

Available Flags:

--incident (required) - Incident ID to acknowledge
--provider - Provider to acknowledge through (e.g., pagerduty)
--api - API server URL override

Status Updates

# Mark incident as mitigated
./bin/im mitigate --incident INC-12345

# Resolve an incident
./bin/im resolve --incident INC-12345

# Close a resolved incident
./bin/im close --incident INC-12345

Each status command follows the same pattern with --incident flag for the incident ID.

Timeline Management

The Timeline Service provides complete event history for incidents with filtering, querying, and export capabilities.

Listing Timeline Events

List and filter timeline events for an incident:

# List all events for an incident
./bin/im timeline list --incident INC-12345

# Filter by event type pattern
./bin/im timeline list --incident INC-12345 --type "im.incident.*"

# Filter by specific event type
./bin/im timeline list --incident INC-12345 --type "im.incident.acknowledge"

# Filter by time range
./bin/im timeline list --incident INC-12345 \
  --from "2025-12-01T00:00:00Z" \
  --to "2025-12-10T23:59:59Z"

# Filter by actor
./bin/im timeline list --incident INC-12345 --actor "oncall@example.com"

# Combine multiple filters
./bin/im timeline list --incident INC-12345 \
  --type "im.alert.*" \
  --from "2025-12-10T00:00:00Z" \
  --limit 100

# Output as JSON
./bin/im timeline list --incident INC-12345 --format json

# JSON with pretty printing
./bin/im timeline list --incident INC-12345 --format json | jq .

Available Flags:

--incident, -i (required) - Incident ID
--type - Event type pattern (supports wildcards: im.incident.*)
--from - Filter events from time (RFC3339 format)
--to - Filter events to time (RFC3339 format)
--actor - Filter by actor (user or system)
--limit - Maximum number of events (default: 50, max: 1000)
--format, -f - Output format: table (default) or json
--api - API server URL (default: http://localhost:8080)

Output Example (Table):

Timeline for incident: INC-1234 (42 events)

TIME                      TYPE                 ACTOR                          TITLE                          ID
----                      ----                 -----                          -----                          --
2025-12-11T10:30:00Z      declare              oncall@example.com             Database Connection Pool E...  550e8400-e29b-41d4-a716...
2025-12-11T10:32:15Z      acknowledge          alice@example.com              Acknowledged by on-call SRE    a1b2c3d4-e5f6-7890-abcd...
2025-12-11T10:45:30Z      note.add             alice@example.com              Investigating connection p...  b2c3d4e5-f6g7-8901-bcde...

(More events available - use pagination)

Getting Specific Events

Retrieve details for a single event:

# Get event details (human-readable)
./bin/im timeline get evt-550e8400-e29b-41d4-a716-446655440000

# Get event as JSON
./bin/im timeline get evt-550e8400-e29b-41d4-a716-446655440000 --format json

Output Example:

Event ID: 550e8400-e29b-41d4-a716-446655440000
Incident: INC-1234
Time:     2025-12-11T10:30:00Z
Type:     im.incident.declare
Actor:    oncall@example.com
Source:   api

Title:
  Database Connection Pool Exhausted

Content:
  Payment API experiencing connection timeouts affecting 15% of requests.

Data:
  {
    "severity": "SEV-2",
    "service": "payments-api",
    "region": "us-east-1"
  }

Extensions:
  im.incident_id: INC-1234
  im.actor: oncall@example.com
  im.origin_id: pagerduty:alert:ABC123

Exporting Timelines

Export complete incident timelines in various formats:

# Export as JSON (CloudEvents v1.0 format)
./bin/im timeline export --incident INC-12345 --format json > timeline.json

# Export as Markdown (report format)
./bin/im timeline export --incident INC-12345 --format markdown > postmortem.md

# Short form for markdown
./bin/im timeline export --incident INC-12345 --format md > report.md

Export Formats:

JSON - CloudEvents v1.0 compliant array for programmatic processing
Markdown - Human-readable report format for postmortems and documentation

JSON Export Example:

[
  {
    "specversion": "1.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "source": "im://api",
    "type": "im.incident.declare",
    "subject": "incident/INC-1234",
    "time": "2025-12-11T10:30:00Z",
    "datacontenttype": "application/json",
    "data": {
      "title": "Database Connection Pool Exhausted",
      "severity": "SEV-2",
      "service": "payments-api"
    },
    "im.actor": "oncall@example.com",
    "im.incident_id": "INC-1234",
    "im.origin_id": "pagerduty:alert:ABC123"
  }
]

Markdown Export Example:

# Incident Timeline: INC-1234

**Generated**: 2025-12-11T15:30:00Z
**Events**: 42

## Events

### 2025-12-11T10:30:00Z - Incident Declared

**Actor**: oncall@example.com
**Type**: im.incident.declare

Database Connection Pool Exhausted

Payment API experiencing connection timeouts affecting 15% of requests.

---

### 2025-12-11T10:32:15Z - Incident Acknowledged

**Actor**: alice@example.com
**Type**: im.incident.acknowledge

Acknowledged by on-call SRE. Investigating connection pool settings.

Common Timeline Workflows

Postmortem Report Generation:

# Export timeline as markdown for postmortem
./bin/im timeline export --incident INC-12345 --format markdown > postmortem_INC-12345.md

# Add additional context
echo "## Root Cause Analysis" >> postmortem_INC-12345.md
echo "Database connection pool configuration was too small..." >> postmortem_INC-12345.md

Programmatic Timeline Analysis:

# Export as JSON and analyze with jq
./bin/im timeline export --incident INC-12345 --format json | \
  jq '[.[] | select(.type | startswith("im.alert"))] | length'

# Find all events by specific actor
./bin/im timeline list --incident INC-12345 --format json | \
  jq '.events[] | select(.actor == "system:pagerduty")'

Time-Range Analysis:

# Get all events during incident response (first hour)
./bin/im timeline list --incident INC-12345 \
  --from "2025-12-11T10:00:00Z" \
  --to "2025-12-11T11:00:00Z" \
  --format json

Timeline Commands Summary

Command	Description	Required Flags
`timeline list`	List timeline events with filters	`--incident`
`timeline get`	Get specific event details	event-id (positional)
`timeline export`	Export complete timeline	`--incident`, `--format`

Event Type Patterns

Timeline events follow CloudEvents v1.0 with the im.* namespace:

Incident Lifecycle:

im.incident.declare - New incident created
im.incident.acknowledge - Incident acknowledged
im.incident.escalate - Incident escalated
im.incident.resolve - Incident resolved
im.incident.close - Incident closed

Alert Events:

im.alert.trigger - New alert received
im.alert.acknowledge - Alert acknowledged
im.alert.resolve - Alert resolved

Collaboration:

im.note.add - Note added to timeline
im.status_update.post - Status update posted
im.runbook.execute - Runbook execution

Integration Sync:

im.servicenow.sync - ServiceNow ticket synchronized
im.jira.sync - Jira issue synchronized
im.slack.message - Slack message linked

Use Wildcards for Filtering:

im.incident.* - All incident lifecycle events
im.alert.* - All alert-related events
im.* - All events (default when no type specified)

System Operations

Server Management

# Start the web server
./bin/im serve

# Start on different port
./bin/im serve --port 9090

# Development mode with additional logging
./bin/im serve --dev

Live Event Streaming

# Stream live incident events
./bin/im live

# Note: Requires server to be running with real-time features

Integration Management

Connector Management

Manage ITSM system integrations (ServiceNow, Jira Service Management):

# List configured connectors
./bin/im connector list

# Add a new connector
./bin/im connector add --name servicenow-prod --type servicenow --url https://your-instance.service-now.com

# Remove a connector
./bin/im connector remove --name servicenow-prod

# Test connector connection
./bin/im connector test --name servicenow-prod

# Manually sync an incident to a connector
./bin/im connector sync --name servicenow-prod --incident INC-12345

Connector Commands:

list - Show all configured connectors
add - Add new ITSM connector
remove - Remove connector configuration
test - Test connector connectivity
sync - Manual incident synchronization

ChatOps Management

Manage chat platform integrations:

# List ChatOps providers
./bin/im chatops list

# Add Slack integration
./bin/im chatops add --name slack-ops --type slack --webhook-url https://hooks.slack.com/...

# Test ChatOps provider
./bin/im chatops test --name slack-ops

# Send test notification
./bin/im chatops notify --name slack-ops --message "Test incident notification"

# Remove ChatOps provider
./bin/im chatops remove --name slack-ops

ChatOps Commands:

list - Show configured chat providers
add - Add new ChatOps integration
remove - Remove ChatOps provider
test - Test provider connectivity
notify - Send test notification

Analytics & Monitoring

Metrics and Analytics

View comprehensive incident analytics:

# Incident metrics overview
./bin/im metrics overview

# Team performance metrics
./bin/im metrics team

# Service reliability metrics
./bin/im metrics service --service api

# Compare metrics between time periods
./bin/im metrics compare --range 7d

# Custom time range
./bin/im metrics overview --range 30d --server http://localhost:8080

Metrics Commands:

overview - General incident metrics
team - Team performance analysis
service - Service-specific reliability metrics
compare - Period-over-period comparison

Common Flags:

--range - Time range: 24h, 7d, 30d, 90d (default: 7d)
--format - Output format: table, json (default: table)

SLA Management

Track and monitor SLA compliance:

# Get SLA status for an incident (requires incident ID from server)
./bin/im sla status --incident INC-12345

# View aggregate SLA metrics
./bin/im sla metrics

# SLA metrics with custom time range
./bin/im sla metrics --since 2025-08-01 --until 2025-08-31

Correlation Operations

Manage incident correlation and grouping:

# Run correlation analysis
./bin/im correlate analyze

# View correlation groups
./bin/im correlate groups

# Correlation statistics
./bin/im correlate stats

Escalation Management

Manage incident escalation rules:

# List all escalation rules
./bin/im escalation list

# Create new escalation rule
./bin/im escalation create --name "SEV-1 Escalation" --trigger-time 15m

# Update existing rule
./bin/im escalation update --id rule-123 --trigger-time 10m

# Delete escalation rule
./bin/im escalation delete --id rule-123

# View escalation templates
./bin/im escalation templates

# Show escalation history for incident
./bin/im escalation history --incident INC-12345

Utility Commands

Shell Completion

Generate shell completion scripts:

# Generate bash completion
./bin/im completion bash > /etc/bash_completion.d/im

# Generate zsh completion
./bin/im completion zsh > "${fpath[1]}/_im"

# Generate fish completion
./bin/im completion fish > ~/.config/fish/completions/im.fish

# Generate PowerShell completion
./bin/im completion powershell > im.ps1

Help System

Get help for any command:

# General help
./bin/im help

# Command-specific help
./bin/im declare --help
./bin/im metrics --help
./bin/im connector --help

# Subcommand help
./bin/im metrics overview --help
./bin/im connector add --help

Development & Testing

Server Requirements

Most CLI commands require the API server to be running:

# Start server in one terminal
./bin/server

# Use CLI in another terminal
./bin/im declare --title "Test incident" --sev SEV-2

Testing Commands

Test CLI functionality:

# Test server connection
curl http://localhost:8080/health

# Test basic CLI operations
./bin/im --help
./bin/im declare --title "CLI Test" --sev SEV-4
./bin/im timeline list

Common Issues

Connection Refused:

Error: failed to connect to server: Post "http://localhost:8080/api/v1/incidents": dial tcp 127.0.0.1:8080: connect: connection refused

Solution: Ensure ./bin/server is running first

Command Not Found:

./bin/im: No such file or directory

Solution: Run make build to create CLI binary

This CLI documentation reflects the current working commands that have been tested with the running server. Future releases will expand available functionality as the platform continues development.

Edit this page on GitHub

types Package

Connector Testing

CLI Reference

Overview#

Installation & Setup#

Build from Source#

Configuration#

Server Connection#

Custom Server URL#

Command Categories#

Core Incident Operations#

System Operations#

Integration Management#

Analytics & Monitoring#

Timeline & Reporting#

Utility Commands#

Incident Management#

Creating Incidents#

Managing Incidents#

Acknowledging Incidents#

Status Updates#

Timeline Management#

Listing Timeline Events#

Getting Specific Events#

Exporting Timelines#

Common Timeline Workflows#

Timeline Commands Summary#

Event Type Patterns#

System Operations#

Server Management#

Live Event Streaming#

Integration Management#

Connector Management#

ChatOps Management#

Analytics & Monitoring#

Metrics and Analytics#

SLA Management#

Correlation Operations#

Escalation Management#

Utility Commands#

Shell Completion#

Help System#

Development & Testing#

Server Requirements#

Testing Commands#

Common Issues#

Overview

Installation & Setup

Build from Source

Configuration

Server Connection

Custom Server URL

Command Categories

Core Incident Operations

System Operations

Integration Management

Analytics & Monitoring

Timeline & Reporting

Utility Commands

Incident Management

Creating Incidents

Managing Incidents

Acknowledging Incidents

Status Updates

Timeline Management

Listing Timeline Events

Getting Specific Events

Exporting Timelines

Common Timeline Workflows

Timeline Commands Summary

Event Type Patterns

System Operations

Server Management

Live Event Streaming

Integration Management

Connector Management

ChatOps Management

Analytics & Monitoring

Metrics and Analytics

SLA Management

Correlation Operations

Escalation Management

Utility Commands

Shell Completion

Help System

Development & Testing

Server Requirements

Testing Commands

Common Issues