Observe CLI

Command line interface for Observe Inc.

Features

• Knowledge Graph 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.
• Datastream Management - Create, list, view, and update datastreams.
• 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 agent skills shipped under skills/:

npx skills add observeinc/cli

To update installed skills after edits in this repo, run npx skills update.

Commands

Note: some commands listed below are temporarily disabled in this build. They depend on generated GraphQL/REST types that cannot be regenerated while the target tenant has GraphQL introspection disabled. They are commented out in src/app.ts (search for "TEMP: trimmed pending full Observe schema access") and will be restored once bun codegen:gql can run. The currently active commands are: help, dataset, alert, board, folder, opal, fleet, schema, worksheet, cli.

schema introspect additionally requires the tenant to have GraphQL introspection enabled. dataset dry-run and dataset impact are wired but unverified on this tenant: their underlying operations drifted (saveDatasetDryRun removed; getDatasetsAffectedByDatasetUpdate result fields renamed) and the new shapes cannot be re-derived without introspection.

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 tag-value list	Search tag values in the knowledge graph
observe tag-key list	Search tag keys in the knowledge graph
observe dataset list	List datasets with optional filtering
observe dataset view	View dataset details and schema
observe dataset dry-run	Dry-run a dataset pipeline change (unverified on tenant)
observe dataset impact	Report datasets affected by a change (unverified)
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 alert list	List alerts with severity and status filtering
observe alert view	View full alert details
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 board create	Create a board (dashboard) from a JSON file
observe board update	Update an existing board from a JSON file
observe board get	Get a board by ID as JSON
observe board list	List boards in a workspace
observe board delete	Delete a board by ID
observe board scaffold	Print a minimal board JSON template
observe board set-default	Set the default dashboard for a dataset
observe board clear-default	Clear the default dashboard for a dataset
observe folder create	Create a folder (use --ensure to make it idempotent)
observe folder get	Look up a folder by name and print its ID
observe folder update	Update a folder's name, description, or icon URL
observe folder delete	Delete a folder by ID
observe opal check	Validate an OPAL pipeline and print its result schema
observe opal verbs	List all OPAL verbs
observe opal functions	List all OPAL functions
observe opal validate-ingest	Validate an OPAL ingest filter against a dataset
observe fleet status	Current status of all observe-agent instances
observe fleet host	observe-agent details for a single host
observe fleet versions	observe-agent versions across the fleet
observe fleet auth	observe-agent auth-check status across the fleet
observe schema introspect	Dump the GraphQL schema as JSON (introspection req'd)
observe worksheet list	List worksheets in a workspace
observe worksheet get	Get a worksheet by ID as JSON
observe worksheet create	Create a worksheet from a JSON file
observe worksheet delete	Delete a worksheet by ID
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 session
export 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

Agent Skills

This repo ships skills under skills/. Install them with the skills CLI:

npx skills add observeinc/cli

To update installed skills after edits in this repo, run npx skills update.

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