observal-cli 1.2.1

Observal MCP Server Registry & Agent Registry CLI

 ██████╗ ██████╗ ███████╗███████╗██████╗ ██╗   ██╗ █████╗ ██╗
██╔═══██╗██╔══██╗██╔════╝██╔════╝██╔══██╗██║   ██║██╔══██╗██║
██║   ██║██████╔╝███████╗█████╗  ██████╔╝██║   ██║███████║██║
██║   ██║██╔══██╗╚════██║██╔══╝  ██╔══██╗╚██╗ ██╔╝██╔══██║██║
╚██████╔╝██████╔╝███████║███████╗██║  ██║ ╚████╔╝ ██║  ██║███████╗
 ╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚═╝  ╚═╝╚══════╝

A self-hosted registry for distributing AI coding agents across your team, with shared observability built in. Every session, prompt, and tool call is captured. Enterprise edition adds AI-powered insights, HIPAA audit logging, and SSO.

If you find Observal useful, please consider giving it a star. It helps others discover the project and keeps development going.

---

Supported IDEs

IDE
Claude Code
Kiro
Cursor
Pi

One command to install any agent into any supported IDE. The config files are generated per-IDE automatically.

---

Quick Start

One-line server install

curl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install-server.sh | bash

Downloads a config package, runs guided setup, pulls Docker images from GHCR, and starts the full stack.

From source

git clone https://github.com/BlazeUp-AI/Observal.git && cd Observal
cp .env.example .env
make up

Install the CLI

# pip / pipx (all platforms)
pipx install observal-cli

# Or with uv
# uv tool install observal-cli

# Homebrew (macOS, Linux)
# brew install BlazeUp-AI/observal/observal-cli

Connect your IDE

observal auth login
observal doctor --patch

This registers your IDE, installs telemetry hooks, and starts capturing sessions automatically.

Once logged in, run /observal inside your IDE and it'll take the wheel. Pull agents, submit components, browse the registry, run diagnostics, manage your setup:

/observal pull security-auditor
/observal scan
/observal doctor

Or just tell your agent what you want and it'll figure out the right commands via the CLI.

---

What Observal Does

Agents are the primary unit

An agent bundles 5 component types into a single installable package: MCP servers, skills, hooks, prompts, and sandboxes. You define them in YAML, publish to the registry, and anyone can pull them with one command. The platform generates the right config files for whichever IDE the user runs.

observal pull security-auditor --ide pi

Every session becomes a trace

Once connected, Observal captures your entire coding session: every user prompt, every thinking block, every assistant response, every tool call with its full input and output. No sampling, no summarization. The raw session flows into ClickHouse for querying and analysis.

The registry is a package manager for agents

Browse published agents, see which IDEs they support, check download counts and ratings, and install with one command. Admins review submissions before they go live. Version diffs show exactly what changed between releases.

---

Session Observability

Full session overview with token counts, models, tools, and turn-by-turn timeline:

Every turn captured: user prompt, tool calls, thinking block, assistant response:

Drill into any span to see exact tool inputs and outputs:

---

Agent Registry

Browse, search, and install agents with IDE compatibility badges:

Build agents visually with live config preview for every IDE:

Components library: MCPs, Skills, Hooks, Prompts, Sandboxes:

---

Review and Governance

Admin review queue with full prompt inspection and approve/reject:

Version diffs show exactly what changed between releases:

Leaderboard tracks top agents and components by downloads:

---

Enterprise Edition

Source-available under a separate license. Activated with a signed JWT key. Core never imports from ee/, the open-source edition is fully functional without it.

Enterprise adds:

• AI-powered insight reports analyzing usage patterns across all sessions
• HIPAA audit logging with sensitivity classification, chain hashes, and CSV export
• SAML SSO and SCIM provisioning
• Executive dashboard for org-wide agent performance

HIPAA-compliant audit log with parameterized search:

AI insight reports generated from session telemetry:

# Enterprise install
curl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install-server.sh | bash -s -- --license-key YOUR_KEY

---

Documentation

Full docs at docs.observal.io

---

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, Tailwind CSS 4, shadcn/ui
Backend	Python 3.11+, FastAPI, Strawberry GraphQL
Databases	PostgreSQL 16 (registry), ClickHouse (telemetry)
Queue	Redis + arq
CLI	Python, Typer, Rich
Telemetry	Session hooks, stdio shims, push-based ingest
Deployment	Docker Compose (10 services)

Contributing

See CONTRIBUTING.md. The short version:

1. Fork and clone
2. make hooks to install pre-commit hooks
3. Create a feature branch
4. Run make lint and make test
5. Open a PR

See AGENTS.md for internal codebase context.

Community

GitHub Discussions for questions and ideas. Discord for chat. Open Issues for confirmed bugs.

Reporting Issues

observal support bundle

Produces a redacted diagnostic archive. Review before sharing: observal support inspect observal-support-*.tar.gz

For live debugging, Observal uses loguru-based dev logging (internally called "optic"). Stream logs with:

observal logs

Logs are written to ~/.observal/logs/dev.log and include structured context for every request, background job, and telemetry event.

Security

Report vulnerabilities via GitHub Private Vulnerability Reporting or email [e-mail]. Do not open a public issue. See SECURITY.md.

Star History

License

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.