Observe CLI

Command line interface for Observe Inc.

Features

• Tag Search - Resolve entities and entity types via tag keys and tag values to ground investigations in real data.
• Dataset Management - List, view, and explore datasets with filtering and field selection.
• Metric Exploration - Search, list, and inspect metrics including type, unit, and available dimensions.
• OPAL Query Execution - Run OPAL queries directly from your terminal with schema-aware table output.
• AI Agent Skills - List and view reusable AI-agent instruction documents stored in Observe.
• Alert Monitoring - List and view alerts with severity filtering and active-only views.
• Monitor Mutes - Full CRUD for monitor mute rules (snoozes), targeting all monitors or a specific set.
• Datastream Management - Create, list, view, and update datastreams.
• Documentation Search - Semantic search across Observe's built-in documentation from your terminal.
• Multiple Output Formats - All commands support --format json and --format csv for scripting and pipelines.
• Responsive Tables - Terminal-aware column widths with automatic text wrapping.

Installation

Install the CLI:

curl -fsSL https://raw.githubusercontent.com/observeinc/cli/main/install.sh | bash

Install the Observe agent skills into your coding agents:

observe skill install --all

Commands

Command	Description
observe help	Show help information
observe auth login	Authenticate with Observe (browser or device code flow)
observe auth logout	Clear stored credentials
observe auth status	Show current authentication status
observe auth configure	Manually configure CLI credentials
observe auth profile list	List all saved profiles
observe auth profile use	Switch the default profile
observe tag-value list	Search tag values
observe tag list	Search tags
observe dataset list	List datasets with optional filtering
observe dataset view	View dataset details and schema
observe metric list	Search and list metrics
observe metric view	View metric details and dimensions
observe query	Execute OPAL queries on datasets
observe skill list	List AI agent skills
observe skill view	View skill details and content
observe skill install	Install skills into your coding agents
observe skill update	Update installed skills to the latest version
observe alert list	List alerts with severity and status filtering
observe alert view	View full alert details
observe monitor mute list	List and search monitor mute rules
observe monitor mute view	View full monitor mute rule details
observe monitor mute create	Create a monitor mute rule
observe monitor mute update	Update a monitor mute rule
observe monitor mute delete	Delete a monitor mute rule
observe datastream create	Create a new datastream
observe datastream list	List datastreams
observe datastream view	View a datastream by ID
observe datastream update	Update a datastream
observe datastream-token check-status	Poll a datastream token until ingest data arrives
observe docs search	Search Observe's documentation
observe cli install	Configure shell integration (PATH, completions)
observe cli uninstall	Remove shell integration
observe cli upgrade	Upgrade to the latest version

Experimental commands

Experimental commands are hidden by default and gated behind an environment variable. They are not covered by SemVer — their names, flags, and output may change or be removed without notice.

# Enable experimental commands for the sessionexport OBSERVE_CLI_EXPERIMENTAL=1
observe help# experimental commands now appear, tagged [experimental]

Configuration

Credentials are stored in ~/.observe/config.json with mode 600 (owner-only access). Permissions are automatically enforced on every write.

# Browser-based login (recommended)
observe auth login
# Login to a specific customer
observe auth login --url 123456.observeinc.com
# Device code flow (for headless environments)
observe auth login --useDeviceCode --url 123456.observeinc.com
# Check current auth status
observe auth status
# Manual configuration
observe auth configure --domain observeinc --customerId 123456 --token YOUR_API_KEY

Profiles

Profiles let you store credentials for multiple Observe environments (e.g. production and staging) and switch between them easily.

# Login and save credentials under a named profile
observe auth login --profile staging --url 123456.observeinc.com
# List all saved profiles
observe auth profile list
# Permanently switch the default profile
observe auth profile use staging
# Use a profile for a single command without switching the default
OBSERVE_PROFILE=staging observe auth status

Profile selection priority: OBSERVE_PROFILE env var → currentProfile in the config file → "default".

Agent Skills

Agent skills are instruction documents that teach a coding agent how to drive the CLI, write OPAL, and investigate with Observe data. Observe curates a set of them in observeinc/skills; the CLI fetches the current version on demand, so you do not need to clone anything.

# Install every curated skill into each coding agent the CLI detects
observe skill install --all
# Install specific skills by name
observe skill install observe-cli generate-opal
# Install into the current repo rather than your home directory
observe skill install --all --project
# Refresh installed skills to the latest published version
observe skill update

observe skill list shows which skills exist and which are already installed. Skills your organization stores in Observe are reachable with the same commands under --user-defined.

Contributing

Contributions are welcome! For non-trivial changes, please open an issue first so we can align on the approach — the change may already be planned, in progress, or out of scope.

Please use Conventional Commits for commit messages (e.g. fix(query): handle empty result set).

---

Development

Prerequisites

• Bun

Setup

git clone <repository-url>cd cli
bun install

Running Locally

# Run CLI in development mode
bun dev --help
# Run commands
bun dev dataset list
bun dev metric list --match "cpu"
bun dev tag-value list --match checkout

Scripts

bun dev # Run CLI in development mode
bun test# Run codegen, typecheck, lint, format, and unit tests
bun test:integration # Integration tests against a real tenant (requires env vars below)
bun typecheck # Type checking
bun lint # Check for issues
bun format # Check formatting
bun codegen # Generate GraphQL and REST API types

Integration tests

Add credentials to .env (see .env.example), then run:

bun run test:integration

License

Apache-2.0