Monoscope full color logo
Sign Up
Home Getting Started SDK Guides AI Dashboard API Reference
CLI & Agents
MCP Server

On this page

Open in ChatGPT Open in Claude Open in Perplexity

Command Reference

An opinionated tour grouped by use case. Every command supports --help for the complete flag list; the exhaustive reference lives in the GitHub repo.

Global flags

Flag Description
--project/-p <uuid> Override the project for this invocation.
--json Emit JSON (forced anyway when stdout is piped).
--yaml Emit YAML.
--table Force pretty-printed table (overrides pipe → JSON auto-detect).
--debug Print every outgoing request URL to stderr (also: MONOSCOPE_DEBUG=1).

Precedence when multiple are set: --json > --yaml > --table.

Output modes

  • table — default on a TTY. Unicode box-drawing renderer with severity colouring, terminal-width truncation, and a pagination cue under list output. Keep colours when piping with MONOSCOPE_FORCE_COLOR=1.
  • json — default when stdout is a pipe. Pretty-printed, agent-friendly.
  • yaml — config-friendly. Round-trips cleanly through apply for monitors and dashboards.

Logs, traces, events

logs, traces, and events share the same event store. logs and traces are aliases for events with a --kind filter pre-applied.

# Bare strings are auto-rewritten to body has "..." or summary has "..."
monoscope logs search POISON_ROW_DROPPED --since 24h

# Recent errors across all services (KQL)
monoscope events search 'severity.text=="error"' --since 1h

# Service + level shorthands compose with the positional KQL query.
# --service is repeatable; --level normalises to upper-case.
monoscope logs search --service checkout-api --service worker --level error --since 30m

# Free-text search inside the body
monoscope logs search 'body has "payment failed"' --since 1h

# Absolute time range
monoscope traces search --service auth \
  --from 2026-04-01T00:00:00Z --to 2026-04-02T00:00:00Z

# Pagination via cursor
CURSOR=$(monoscope events search "" --since 1h --limit 100 | jq -r .cursor)
monoscope events search "" --since 1h --limit 100 --cursor "$CURSOR"

# "Just give me one event id to chain"
monoscope logs search 'severity.text=="error"' --first --id-only

# Trace tree
monoscope traces get <trace-id> --tree

# Project specific fields out of a single event (no jq needed)
monoscope events get <event-id> --field body --field summary
monoscope events get <event-id> --show-body   # shorthand for the line above

# Live tail with optional grep
monoscope logs tail --service api --level error --grep timeout

# Context window around a timestamp, with per-trace summary for triage
monoscope events context --at 2026-04-15T10:34:22Z --window 10m --summary

Long --since windows on events search / logs search are auto-chunked into 1-hour slices (override with --chunk-hours <H>, disable with --no-chunk) and streamed as NDJSON. Gateway errors (502/503/504, Cloudflare HTML) collapse into a one-liner with a “narrow --since” hint and one jittered retry.

KQL operator reference: see the kql-reference skill. Use ==/!= (not Lucene :) for equality, and/or for logical, has for word-search inside text fields.

Discovery

These two commands tell you what’s actually in your project — run them before writing a query so you don’t waste round-trips on field names that don’t exist or values that never match.

# What fields do I have? (~600 in a default project — narrow with --search)
monoscope schema --search service --limit 20
monoscope schema --search http
monoscope schema -o json | jq '.fields | keys[]' | head -50

# What values does each field have? (Precomputed top-N per field.)
monoscope facets                                   # every faceted field
monoscope facets resource.service.name --top 10    # one field, top 10 values
monoscope facets severity.text                     # which levels are in use?
monoscope facets attributes.http.response.status_code   # which 4xx/5xx happen?

Metrics

# Group event count by service
monoscope metrics query 'summarize count() by resource.service.name'

# p99 latency by service over the last 30 minutes
monoscope metrics query 'summarize percentile(duration, 99) by resource.service.name' --since 30m

# CI-friendly assertion: exit non-zero if condition fails
monoscope metrics query 'summarize count()' --since 30m --assert '< 1000'

# Sparkline charts (bin by 1m)
monoscope metrics chart 'summarize count() by bin(timestamp, 1m)' --since 2h
monoscope metrics chart 'summarize avg(duration) by bin(timestamp, 1m)' --watch 30s

Services

monoscope services list                  # services active in the last 24h
monoscope services list --since 7d       # widen the window

Issues, log patterns, monitors, dashboards

All list commands share a uniform envelope — {data: [...], pagination: {...}} — so the same jq pipelines work everywhere.

# Issues
monoscope issues list --status open --service payment-api \
  | jq '.data[] | {id, title, severity, service}'
monoscope issues get <issue-id>
monoscope issues ack <issue-id>
monoscope issues bulk acknowledge --ids id1,id2,id3

# Log patterns
monoscope log-patterns list --per-page 50 \
  | jq '.data[] | {id, frequency: .occurrence_count, sample: .pattern}'
monoscope log-patterns ack <pattern-id>
monoscope log-patterns bulk ignore --ids 1,2,3

# Monitors (CRUD + lifecycle)
monoscope monitors list
monoscope monitors create monitor.yaml
monoscope monitors apply monitors/                 # idempotent batch upsert
monoscope monitors mute <monitor-id> --for 30      # mute for 30 minutes
monoscope monitors bulk resolve --ids id1,id2

# Dashboards (CRUD + apply)
monoscope dashboards list
monoscope dashboards yaml <id> > dashboard.yaml    # round-trip
monoscope dashboards apply dashboards/             # idempotent
monoscope dashboards widget upsert <dashboard-id> widget.yaml

API keys, teams, members, project

monoscope api-keys create "ops-2026" -o json   # plaintext key shown ONCE
monoscope api-keys deactivate <id>             # soft disable
monoscope api-keys delete <id>                 # permanent

monoscope teams list
monoscope teams create team.yaml

monoscope members list
monoscope members add --email teammate@example.com --permission view
monoscope members patch <user-id> admin

monoscope me                                   # current project identity
monoscope project get
monoscope project patch patch.yaml             # subset: title, description, time_zone, ...

CI / automation tips

# Health-check style assertion in CI
monoscope metrics query 'summarize count()' --since 5m --assert '< 100' \
  || echo "error spike — failing the build"

# Apply monitors from a directory (idempotent — safe to re-run)
monoscope monitors apply .monoscope/monitors/

# Bulk acknowledge stale issues
monoscope issues list --status open --service legacy-billing \
  | jq -r '.data[].id' | head -20 | paste -sd, - \
  | xargs -I {} monoscope issues bulk acknowledge --ids {}

See also