Overview

Complete reference for the observal CLI. Every subcommand has its own page; this overview is the index.

New to Observal? Start with Quickstart and come back here when you need a specific command.

Command groups

Command	What it does
`observal api`	Call authenticated JSON endpoints without a dedicated command
`observal auth`	Authentication and account management
`observal config`	Local CLI configuration, aliases
`observal discover`	Find approved resources for a task and use them in the current session
`observal scan`	Discover what’s installed across your harnesses (read-only)
`observal share`	Share and pull scoped, version-pinned repository Agent sets
`observal outdated`	Compare installed agent and component versions with the active registry
`observal reconcile`	Backfill sessions missed by automatic telemetry delivery
`observal inbox`	Read and update the signed-in user’s work and event feed
`observal agent pull`	Install a published agent into a harness
`observal registry`	Publish and manage components (MCP / skill / hook / prompt / sandbox)
`observal registry recommend`	Get personalized component recommendations
`observal registry version`	Publish and inspect component versions
`observal registry models`	Inspect packaged harness model catalogs
`observal agent`	Create, install, and manage agents
`observal team`	Manage teamspaces, members, join requests, and invitations
`observal ops`	Observability and operations (sessions, telemetry, logs, insights)
`observal admin`	Core administration and submission review
`observal doctor support`	Generate and inspect redacted diagnostic bundles
`observal doctor`	Diagnose harness compatibility; `doctor patch` applies instrumentation
`observal server migrate`	Export/import PostgreSQL registry (shallow copy) and ClickHouse telemetry (deep copy)
`observal self`	Upgrade or downgrade the CLI
`observal registry prompt`	Manage reusable prompts in the registry
`observal server`	Manage the embedded server (start, stop, upgrade, rollback)
`observal registry skill`	Submit, browse, and install portable skill packages

Global options

Any subcommand accepts these.

Option	Short	Description
`--version`	`-V`	Print the CLI version and exit
`--verbose`	`-v`	Verbose output
`--debug`	-	Debug-level logging (extremely verbose)
`--help`	-	Show help for any command or subcommand

JSON list contract

Every dedicated list command returns the same envelope:

{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 0
}

Paginated commands preserve server totals and requested pages. Unpaginated commands use page 1 and the returned item count as page_size. Detail and mutation commands return direct objects. observal api intentionally preserves raw endpoint JSON.

Exit codes

Consistent across all commands:

Code	Meaning
0	Success
1	Unexpected or uncategorized failure
2	Usage error
3	Authentication required or failed
4	Permission denied
5	Resource not found
6	Conflict with current state
7	Validation failure
8	Rate limit reached
9	Network, service, or dependency unavailable
10	CLI and server version mismatch
11	Batch completed with one or more item errors

Errors identify the failed operation, resource, remediation, and server request ID when available. Repairable failures may include a safe structured result; internal details appear only with --debug. When JSON output is selected, errors are written to stderr as one JSON object and stdout remains clean. Startup migrations and update notices never write to JSON stdout. A nonfatal startup migration warning is a structured warning object on stderr.

{
  "error": {
    "category": "not_found",
    "message": "The requested resource was not found.",
    "operation": "Show agent",
    "resource": "agent registry",
    "remediation": "Check the identifier or list available agents.",
    "request_id": "01J...",
    "http_status": 404,
    "exit_code": 5
  }
}

Non-interactive mode

For scripts and CI, pair flags with environment variables:

export OBSERVAL_SERVER_URL=https://observal.your-company.internal
export OBSERVAL_API_KEY='replace-with-your-key'

observal ops traces --limit 100 --output json | jq

Full env var reference: Environment variables.

Output formats

Read-heavy commands (list, show, traces, spans) support --output:

observal registry mcp list --output table    # default, TTY-friendly
observal registry mcp list --output json     # machine-readable

Aliases

IDs get long fast. Create shortcuts:

observal config alias my-mcp 498c17ac-1234-4567-89ab-cdef01234567
observal registry mcp show @my-mcp

See observal config for details.

→ observal auth: you’ll need to log in first.

Getting Started

Core Concepts

Use Cases

CLI Reference

Self-Hosting

Integrations

Reference

Security

Architecture Decisions

Contributing

Command groups

Global options

JSON list contract

Exit codes

Non-interactive mode

Output formats

Aliases

Next

​Command groups

​Global options

​JSON list contract

​Exit codes

​Non-interactive mode

​Output formats

​Aliases

​Next

Command groups

Global options

JSON list contract

Exit codes

Non-interactive mode

Output formats

Aliases

Next