Monitoring from the CLI

Run every Cognition view from your terminal, poll for new events, build automated health check scripts, and wire Cognition data into your alerting systems.

What you'll be able to do after this module

Run the full Cognition capability from the terminal, build a daily health check script, investigate incidents without opening a browser, and wire automated monitoring into your workflow.

Why use the CLI for monitoring

The Console gives you a visual layout. The CLI gives you:

Scriptability — define a health check once, run it anywhere
Composability — pipe output to jq, grep, mail, or any other tool
Speed — one command for an immediate health read, no browser needed
Automation — polling loops, scheduled jobs, CI gates

Everything in Cognition is accessible from the CLI. This module covers the full command set and shows how to combine them into real workflows.

The full Cognition CLI command set

All commands start with skytells cognition <subcommand>.

Subcommand	What it returns
`overview`	Error counts, security events, anomaly flags, performance summary
`errors`	Grouped application error events
`security`	Security threat events
`runtime`	Current CPU, memory, heap, latency
`anomalies`	Detected behavioral anomalies
`events`	Live event stream, filterable by time
`timeseries`	Bucketed metric data over a time window

Command reference

Overview

skytells cognition overview
skytells cognition overview --hours 24    # Last 24 hours
skytells cognition overview --json

Errors

skytells cognition errors
skytells cognition errors --limit 50      # Default is 20
skytells cognition errors --offset 20     # Pagination
skytells cognition errors --json

Security

skytells cognition security
skytells cognition security --json

Runtime Health

skytells cognition runtime
skytells cognition runtime --json

Anomalies

skytells cognition anomalies
skytells cognition anomalies --json

Events

skytells cognition events
skytells cognition events --limit 50
skytells cognition events --since evt-100    # fetch events after this event ID
skytells cognition events --json

Time-series

skytells cognition timeseries
skytells cognition timeseries --hours 48    # Default is 24
skytells cognition timeseries --json

Workflow 1: Daily health check

Run this every morning to get a read on where things stand before you start work:

#!/bin/bash
# daily-health-check.sh

echo "============================================"
echo " Skytells Daily Health Check — $(date -u '+%Y-%m-%d %H:%M UTC')"
echo "============================================"

echo ""
echo "--- OVERVIEW (last 24 hours) ---"
skytells cognition overview --hours 24

echo ""
echo "--- ERRORS ---"
skytells cognition errors --limit 5

echo ""
echo "--- SECURITY THREATS ---"
skytells cognition security

echo ""
echo "--- ANOMALIES ---"
skytells cognition anomalies

echo ""
echo "--- RUNTIME HEALTH ---"
skytells cognition runtime

echo ""
echo "--- APP STATUS ---"
skytells status

Run it:

chmod +x daily-health-check.sh
./daily-health-check.sh

Or schedule it with cron:

# Every morning at 8am (in your local timezone)
0 8 * * * /path/to/daily-health-check.sh >> ~/skytells-health.log 2>&1

Workflow 2: Incident investigation from the terminal

When something is wrong and you want the full picture fast:

#!/bin/bash
# incident-investigation.sh
# Usage: ./incident-investigation.sh [hours]

HOURS="${1:-1}"  # Default to last 1 hour

echo "=== Incident Investigation — Last ${HOURS}h ==="
echo ""

echo "[1/5] Overview..."
skytells cognition overview --hours "$HOURS" --json | jq '{errors: .error_count, security_events: .security_event_count, anomalies: .anomaly_count}'

echo ""
echo "[2/5] Top errors..."
skytells cognition errors --limit 10 --json | jq '[.[] | {type: .type, count: .count, first_seen: .first_seen, last_seen: .last_seen}]'

echo ""
echo "[3/5] Security events..."
skytells cognition security --json | jq '[.[] | {type: .type, severity: .severity, source: .source}]'

echo ""
echo "[4/5] Active anomalies..."
skytells cognition anomalies --json | jq '[.[] | {type: .type, severity: .severity, app: .app}]'

echo ""
echo "[5/5] Runtime health..."
skytells cognition runtime --json | jq '{cpu: .cpu_usage, memory: .memory_usage}'

echo ""
echo "=== Recent deployments ==="
skytells deployments ls --limit 5 --json | jq '[.[] | {id: .id, app: .app, status: .status, created_at: .created_at}]'

Workflow 3: Automated monitoring with polling

The --since <event-id> flag lets you fetch only events that are newer than the last one you received. This is the correct way to poll for new events — track the last event ID, not a timestamp.

#!/bin/bash
# monitor.sh
# Polls Cognition every 5 minutes for new events

POLL_INTERVAL=300   # seconds
LAST_EVENT=""

while true; do
  if [ -z "$LAST_EVENT" ]; then
    RESULT=$(skytells cognition events --limit 1 --json)
  else
    RESULT=$(skytells cognition events --since "$LAST_EVENT" --json)
  fi

  echo "$RESULT"

  # Update LAST_EVENT to the ID of the most recent event received
  NEW_LAST=$(echo "$RESULT" | jq -r '.[-1].id // empty')
  if [ -n "$NEW_LAST" ]; then
    LAST_EVENT="$NEW_LAST"
  fi

  sleep "$POLL_INTERVAL"
done

For production alerting, run this inside a process manager (pm2, systemd, etc.) rather than a bare terminal session. That way it survives disconnections and restarts automatically.

Workflow 4: CI gate on health

Block a deployment from proceeding if Cognition is already showing active problems:

#!/bin/bash
# pre-deploy-health-gate.sh

echo "Running pre-deploy health check..."

# Fail if there are active critical security threats
CRITICAL_SECURITY=$(skytells cognition security --json | jq '[.[] | select(.severity == "critical")] | length')
if [ "$CRITICAL_SECURITY" -gt 0 ]; then
  echo "✗ Blocking deploy: $CRITICAL_SECURITY active critical security threats. Investigate before deploying."
  exit 1
fi

# Fail if error count is above threshold
ERROR_COUNT=$(skytells cognition errors --json | jq 'length')
if [ "$ERROR_COUNT" -gt 50 ]; then
  echo "✗ Blocking deploy: error count is $ERROR_COUNT (threshold: 50). Investigate before deploying."
  exit 1
fi

echo "✓ Health gate passed. Proceeding with deployment."

Add this as a step before your skytells deploy call in CI.

Piping Cognition data to other tools

Because --json output is available on every command, you can pipe it anywhere:

# Write a snapshot to a file
skytells cognition overview --json > health-snapshot-$(date +%Y%m%d).json

# Count errors grouped by type (requires jq)
skytells cognition errors --json | jq 'group_by(.type) | map({type: .[0].type, count: length})'

# Extract all unique security event sources
skytells cognition security --json | jq '[.[] | .source] | unique'

# Time-series memory data for the last 48 hours
skytells cognition timeseries --hours 48 --json | jq '[.[] | {time: .timestamp, memory: .memory_usage}]'

Quick reference

Command	Description
`skytells cognition overview --hours N`	Summary for the last N hours
`skytells cognition errors --limit N`	Last N errors
`skytells cognition security`	Current security threats
`skytells cognition runtime`	CPU, memory, heap, latency
`skytells cognition anomalies`	Active anomalies
`skytells cognition events --since <event-id>`	Events after a specific event ID
`skytells cognition timeseries --hours N`	Metric time-series for N hours

You've completed the Cognition Monitoring path

You can now observe your apps at every level — errors, security, runtime, anomalies, and live events — from both the Console and the terminal, and wire automated monitoring into your workflow.

What's next:

Skytells CLI → — if you haven't worked through the CLI fundamentals, do that for the full deployment and management picture
Building Production Apps → — environment variable patterns, webhook handling, and production-grade integration
Orchestrator Mastery → — automated multi-step workflows using Skytells's orchestration layer

PreviousRuntime Health & Live Events

On this page