| 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 |
Observal: Core CLI Operations
Critical Rules
- EXECUTE commands: run them in your shell, do not just display them.
- Set timeout to 60 seconds: most commands make HTTP calls.
- Use single quotes for
--prompt and --description values to avoid shell quoting issues.
- Do NOT run
observal auth status first. Other commands surface auth problems clearly on their own.
- When in doubt about a flag, run
<command> --help first. Never guess flag names.
- Pass
--output json on every list/show command. It is stable and machine readable.
- Pass
--yes / -y on destructive commands so they do not block on a confirmation prompt.
- Resolve 409 conflicts deterministically:
--update for in-place edits, --bump for versioned releases.
- Only fall back to local file writes if a command exits with
Connection failed or Not configured.
- Never invent
OTEL_* or CLAUDE_CODE_ENABLE_TELEMETRY environment variables. Telemetry flows through observal-shim and session push hooks only.
Procedure: Pull Agent
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.
Procedure: Scan IDEs
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.
Procedure: Doctor
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.
Procedure: Doctor Patch
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.
Procedure: Doctor Cleanup
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
Procedure: Auth
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).
Procedure: CLI Config
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 Reference
| 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 |
Output Contract
For every CLI invocation, format your response:
- One sentence stating intent.
- The exact command in a fenced code block.
- The result: success / specific error.
- The next action, or "done".
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.
