// Core Observal CLI operations: pull agents into your IDE, scan installed components, diagnose and patch IDE configs, authenticate, and manage CLI settings. Use when the user wants to install an agent, check their IDE setup, login, or configure the CLI.
| name | observal |
| command | observal |
| description | Core Observal CLI operations: pull agents into your IDE, scan installed components, diagnose and patch IDE configs, authenticate, and manage CLI settings. Use when the user wants to install an agent, check their IDE setup, login, or configure the CLI. |
| version | 2.0.0 |
| owner | observal |
--prompt and --description values to avoid shell quoting issues.observal auth status first. Other commands surface auth problems clearly on their own.<command> --help first. Never guess flag names.--output json on every list/show command. It is stable and machine readable.--yes / -y on destructive commands so they do not block on a confirmation prompt.--update for in-place edits, --bump for versioned releases.Connection failed or Not configured.OTEL_* or CLAUDE_CODE_ENABLE_TELEMETRY environment variables. Telemetry flows through observal-shim and session push hooks only.Install an agent's full config (rules, MCP servers, hooks, skills) into a local IDE.
observal agent pull AGENT_NAME --ide kiro --no-prompt --dir .
Flags:
--ide (required): claude-code, kiro, cursor, gemini-cli, vscode, codex, copilot, copilot-cli, opencode--scope user|project: install scope (Claude Code, Kiro, Gemini only)--model <name> or --model <ide>=<name>: override saved model (repeatable)--tools t1,t2: Claude Code tool whitelist--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 IDE config files, not overwritten. Existing user entries are preserved.
If the user did not specify an IDE, ask which one before running.
Read-only inventory of installed components across all detected IDEs. Never modifies any file.
observal scan
observal scan --ide kiro
observal scan --ide claude-code
Reports: detected IDEs, MCP servers (with shimmed status), skills, hooks, agents, and unregistered components.
Diagnose only. Does not fix anything.
observal doctor
Reports: Observal config validity, server reachability, hook installation status per IDE, skill presence. Exits non-zero if issues found.
Apply instrumentation. Run with --dry-run first when the user is unsure.
observal doctor patch --all --all-ides --dry-run
observal doctor patch --all --all-ides
observal doctor patch --hook --shim --ide kiro
observal doctor patch --all --ide claude-code
observal doctor patch --hook --all-ides
observal doctor patch --shim --all-ides
Required: at least one of --hook / --shim / --all, AND at least one of --all-ides / --ide. Creates timestamped backups before modifying any file.
Remove Observal-managed hooks and env vars from IDE configs. Leaves user content untouched.
observal doctor cleanup --dry-run
observal doctor cleanup
observal doctor cleanup --ide kiro
observal auth login
observal auth login --server https://observal.example.com
observal auth login --sso
observal auth login --email me@x.com --password '...'
observal auth whoami --output json
observal auth status
observal auth logout
observal auth change-password
observal auth set-username new-handle
On a fresh server, auth login auto-bootstraps an admin from localhost (no prompts needed).
observal config show
observal config path
observal config set output json
observal config set server_url https://observal.example.com
observal config aliases
observal config alias MY_AGENT abc-123
| Error | Action |
|---|---|
Connection failed | Server unreachable. Use the observal-advanced skill's Local Fallback procedure |
Not configured / No server | Run observal auth login |
403 Forbidden | Check observal auth whoami; user lacks required role |
404 Not found | Verify name with observal agent list --output json |
For every CLI invocation, format your response:
For full command reference, read references/commands.md. For agent creation use the observal-agents skill. For registry operations use observal-registry. For observability use observal-ops. For admin tasks use observal-admin.
Observal admin operations including user management, enterprise settings, submission review queue, security events, audit logs, and SSO configuration. Use when the user needs to manage users, approve or reject submissions, view security events, or configure SAML/SCIM.
Submit, browse, install, edit, delete, and version MCPs, skills, hooks, prompts, and sandboxes in the Observal registry. Use when the user wants to submit a component, install one, edit a draft, publish a new version, or browse the component library.
Create, update, version, and manage Observal agents. Use when the user wants to create a new agent, update an existing one, release a new version, scaffold a YAML project, add components, build, publish, bulk-create, delete, or restore agents.
Advanced Observal operations including IDE profile swapping, session reconciliation, CLI upgrades and downgrades, complete uninstallation, and local fallback mode for offline use. Use when the user wants to swap IDE profiles, reconcile sessions, upgrade or downgrade the CLI, uninstall Observal, or write agent configs locally when the server is unreachable.
View traces, spans, metrics, feedback, and telemetry health for Observal agents and MCPs. Use when the user wants to see recent traces, check metrics, view top items, submit ratings, or diagnose telemetry pipeline issues.