> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/cli-reference/cli.md). # Overview Complete reference for the `observal` CLI. Every subcommand has its own page; this overview is the index. > **New to Observal?** Start with [Quickstart](/getting-started/quickstart.md) and come back here when you need a specific command. ## Command groups | Command | What it does | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | [`observal api`](/cli-reference/api.md) | Call authenticated JSON endpoints without a dedicated command | | [`observal auth`](/cli-reference/auth.md) | Authentication and account management | | [`observal config`](/cli-reference/config.md) | Local CLI configuration, aliases | | [`observal scan`](/cli-reference/scan.md) | Discover what's installed across your harnesses (read-only) | | [`observal outdated`](/cli-reference/outdated.md) | Compare installed agent and component versions with the active registry | | [`observal reconcile`](/cli-reference/reconcile.md) | Backfill sessions missed by automatic telemetry delivery | | [`observal inbox`](/cli-reference/inbox.md) | Read and update the signed-in user's work and event feed | | [`observal agent pull`](/cli-reference/pull.md) | Install a published agent into a harness | | [`observal registry`](/cli-reference/registry.md) | Publish and manage components (MCP / skill / hook / prompt / sandbox) | | [`observal registry recommend`](/cli-reference/recommend.md) | Get personalized component recommendations | | [`observal registry version`](/cli-reference/component.md) | Publish and inspect component versions | | [`observal registry models`](/cli-reference/models.md) | Inspect packaged harness model catalogs | | [`observal agent`](/cli-reference/agent.md) | Create, install, and manage agents | | [`observal team`](/cli-reference/team.md) | Manage teamspaces, members, join requests, and invitations | | [`observal ops`](/cli-reference/ops.md) | Observability and operations (sessions, telemetry, logs, insights) | | [`observal admin`](/cli-reference/admin.md) | Core administration and submission review | | [`observal doctor support`](/cli-reference/doctor/support.md) | Generate and inspect redacted diagnostic bundles | | [`observal doctor`](/cli-reference/doctor.md) | Diagnose harness compatibility; `doctor patch` applies instrumentation | | [`observal server migrate`](https://github.com/Observal/Observal/blob/main/docs/cli/migrate.md) | Export/import PostgreSQL registry (shallow copy) and ClickHouse telemetry (deep copy) | | [`observal self`](/cli-reference/self.md) | Upgrade or downgrade the CLI | | [`observal registry prompt`](/cli-reference/prompt.md) | Manage reusable prompts in the registry | | [`observal server`](/cli-reference/server.md) | Manage the embedded server (start, stop, upgrade, rollback) | | [`observal registry skill`](/cli-reference/skill.md) | 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: ```json { "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 | Errors identify the failed operation, resource, remediation, and server request ID when available. Internal details appear only with `--debug`. When JSON output is selected, errors are written to stderr as one JSON object and stdout remains clean: ```json { "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: ```bash export OBSERVAL_SERVER_URL=https://observal.your-company.internal export OBSERVAL_API_KEY= observal ops traces --limit 100 --output json | jq ``` Full env var reference: [Environment variables](/reference/environment-variables.md). ## Output formats Read-heavy commands (`list`, `show`, `traces`, `spans`) support `--output`: ```bash observal registry mcp list --output table # default, TTY-friendly observal registry mcp list --output json # machine-readable ``` ## Aliases IDs get long fast. Create shortcuts: ```bash observal config alias my-mcp 498c17ac-1234-4567-89ab-cdef01234567 observal registry mcp show @my-mcp ``` See [`observal config`](/cli-reference/config.md) for details. ## Next → [`observal auth`](/cli-reference/auth.md): you'll need to log in first. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.observal.io/cli-reference/cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.