/observal

# SPDX-FileCopyrightText: 2026 Shaan Narendran <shaannaren06@gmail.com>
# SPDX-FileCopyrightText: 2026 Hemalatha Madeswaran <hemalathamadeswaran@gmail.com>
# SPDX-License-Identifier: Apache-2.0
name: observal
command: observal
description: "Core Observal CLI operations: pull agents into your harness, scan installed components, diagnose and patch harness configs, authenticate, manage CLI settings, get components recommended for you, and discuss agent insights. Use when the user wants to install an agent, check setup, login, configure the CLI, ask what they should install, or ask how an agent is doing."
version: 2.5.0
owner: observal

Observal: Core CLI Operations

Critical Rules

1. **EXECUTE commands**: run them in your shell, do not just display them. 2. **Set timeout to 60 seconds**: most commands make HTTP calls. 3. **Use single quotes** for `--prompt` and `--description` values to avoid shell quoting issues. 4. **Do NOT run `observal auth status` first.** Other commands surface auth problems clearly on their own. 5. **When in doubt about a flag, run `<command> --help` first.** Never guess flag names. 6. **Pass `--output json` on every list/show command.** It is stable and machine readable. 7. **Pass `--yes` / `-y` on destructive commands** so they do not block on a confirmation prompt. 8. **Use canonical registry identities:** prefer the returned `qualified_name` (`namespace/slug`) for agent and component show, install, pull, archive, and transfer commands. Bare names work only when unambiguous. 9. **Resolve 409 conflicts deterministically:** if the error says a name is ambiguous, retry with `namespace/slug`; otherwise use `--update` for in-place edits or `--bump` for versioned releases. 10. **Only fall back to local file writes** if a command exits with `Connection failed` or `Not configured`. 11. **Never invent `OTEL_*` or `CLAUDE_CODE_ENABLE_TELEMETRY` environment variables.** Telemetry flows through session push hooks and reconciliation only.

---

Procedure: Natural-Language Registry Search

For requests like "find me an agent for incident resolution" or "what skill helps design good frontends", extract the useful keywords and search JSON first.

observal agent list --search 'incident resolution' --output json
observal registry skill list --search 'frontend design' --output json
observal registry skill list --team platform-tools --search 'frontend design' --output json
observal registry mcp list --search 'github docker' --output json

Summarize the top matches by `qualified_name`, description, and why they fit. If no results, retry with fewer keywords.

For open-ended asks instead ("what am I missing", "what should I install"), do not guess keywords — ask what fits this user's own sessions with `observal registry recommend --output json`. Check `personalized` first: `false` means no session history yet, so these are merely the most-used components; say so rather than implying they were chosen for the user. Fields and dismissals are in the `observal-registry` skill.

Procedure: Pull Agent

Install an agent's full config (rules, MCP servers, hooks, skills, sandboxes, prompts) into a local harness.

observal agent pull NAMESPACE/AGENT_SLUG --harness kiro --no-prompt --dir .

**For Pi (`--harness pi`):** When pulling for Pi, the CLI downloads the agent into an isolated profile using its stable slug. If two installed namespaces use the same slug, the CLI qualifies the local profile name to avoid a collision. **Crucial:** After pulling, run `/agent <local-profile-name>` inside Pi using the exact local profile name printed by the CLI.

**Flags:**

• `--harness` (required): `claude-code`, `kiro`, `cursor`, `vscode`, `codex`, `copilot`, `copilot-cli`, `opencode`, `antigravity`, `goose`, `pi`
• `--version <semver>`: install a specific version (e.g. `1.2.0`). Omit for latest.
• `--scope user|project`: install scope for harnesses that support user or project installs
• `--model <name>` or `--model <harness>=<name>`: override saved model (repeatable)
• `--tools t1,t2`: Claude Code tool whitelist
• `--env KEY=VALUE`: MCP environment variable value (repeatable)
• `--header Header-Name=VALUE`: MCP auth header value (repeatable)
• `--dry-run`: preview file writes without touching disk
• `--no-prompt`: skip interactive confirmation
• `--dir <path>`: target directory (default: current)

**Merge behavior:** MCP configs are merged with existing harness config files, not overwritten. Existing user entries are preserved.

**Version pinning:** When `--version` is specified, the exact content from that version is installed. The lockfile (`~/.observal/lockfile.json`) records the pin. If another agent depends on the same component at a different version, a warning is displayed.

If the user did not specify an harness, ask which one before running. After install, check local files:

observal scan --harness kiro

`scan` verifies MCPs, skills, hooks, and agents. Prompts/sandboxes are injected into rules/MCP config; use the pull output/lockfile for membership.

---

Procedure: Outdated

Check for newer versions of installed agents and components.

observal outdated
observal outdated --harness claude-code --output json --no-report

Reads `~/.observal/lockfile.json` and compares each pinned version against the registry's latest. Reports a table of outdated items with current vs latest version. Findings also land in your inbox as `update_available` items so they survive between runs; `--no-report` keeps the check purely local. Reporting is best-effort, so the table prints either way.

---

Procedure: Scan harnesses

Read-only inventory of installed components across all detected harnesses. **Never modifies any file.**

observal scan
observal scan --harness kiro
observal scan --harness claude-code

Reports: detected harnesses, MCP servers, skills, hooks, agents, and unregistered components.

---

Procedure: Doctor

Diagnose only. D