---

name: cli description: "Guides safe modification and operation of the Observal Python CLI, including Typer registration, output and error contracts, noninteractive behavior, bundled skill synchronization, and CLI-focused tests." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

Observal CLI Sub-skill

Use this sub-skill when the task touches the Python observal CLI surface: Typer command registration, command groups, command help, table or JSON output, categorized errors, noninteractive automation, CLI/API client behavior, bundled Observal skill synchronization, or CLI-specific tests.

Route the task

Task	Read
Understand where a command is registered, which module owns it, or how output/errors flow	CLI architecture
Add, rename, remove, or use commands under auth, config, scan, doctor, registry, agent, ops, admin, server, or related groups	Command workflows
Change CLI paths, flags, examples, docs, or agent-facing behavior that must be reflected in bundled skills	Bundled skills
Debug install/import failures, dirty JSON mode, API failures, config issues, optional dependency failures, telemetry/harness command failures, or unsafe retries	Troubleshooting
Quickly inspect the imported CLI app and bundled-skill presence	Run scripts/check_cli_contract.py --help

Read the selected reference before editing. Do not depend on repository docs or tests for the operating contract; this sub-skill distills the relevant rules and names.

Operating rules

1. Keep the canonical CLI entry point as observal_cli.main:app; add new top-level groups only when no existing group fits.
2. Use the existing Typer app for the relevant domain module and verify the final command path with help or static introspection before documenting it.
3. Structured commands support --output table|json using OutputMode; JSON mode must write machine JSON only and must not print Rich tables, prompts, spinners, banners, or progress text.
4. API-backed commands use the shared observal_cli.client functions and the shared error contract in observal_cli.errors; add audited labels in observal_cli.error_context for every new client call site.
5. Agent and CI workflows must be noninteractive: expose required inputs as arguments or options, require explicit confirmation flags for destructive JSON mutations, and use dry-run when a multi-resource preview is meaningful.
6. Mutations are sent once. After a timeout or connection failure following a mutation, read current state before retrying.
7. When a path, flag, output shape, example, or behavior changes, update the matching docs/cli page and every affected bundled skill under observal_cli/skills, then regenerate the generated command reference.
8. Verify with the narrow CLI tests plus static contract checks before declaring the change complete.

Boundaries

• The root observal repo skill owns high-level routing, installation summary, provenance, and cross-cutting smoke checks.
• This cli sub-skill owns the Python CLI hierarchy and bundled Observal skill behavior.
• server owns FastAPI routes, data models, migrations, jobs, insights, and server-side auth/admin implementation.
• harness-telemetry owns harness registry entries, adapters, hook specs, session parsers, and telemetry delivery internals.
• web owns the Vite/React/TanStack Router frontend and Playwright guidance.
• repo-development owns contributor policy, lint/test/release/compliance workflows, and change-review mechanics.