/add-command

name: add-command
description: Use this skill when the user asks to "add a command", "implement cx <something>", "new subcommand", "new CLI command", "add a new cx command", "create a command", "add subcommand", "implement a new command", "build a cx command", "wire up a new command", "extend the CLI", "add an API to cx", "new cx feature", "integrate a Coralogix API", or wants to add new functionality to the cx CLI. Use this even when the user describes a feature that implies a new command without saying "command" explicitly.
version: 0.1.0
metadata:
  internal: true

Add a CLI Command

End-to-end workflow for adding a new command to `cx`. Every command falls into one of two archetypes - determine which one first, then follow the corresponding steps.

`docs/adding-a-command.md` has copy-pasteable code templates for every step below. Read it alongside this workflow.

Step 0: Understand What You're Building

Before writing any code, get clarity on the domain:

1. **What Coralogix API are you wrapping?** Find the API docs or example responses. Understand the data model - what entities exist, what fields they have, what operations are supported. 2. **What should the user be able to do?** List the subcommands (e.g., `list`, `get`, `create`) and what flags make sense. 3. **Does this belong under a wrapper group?** The CLI organizes related commands into wrapper groups. Check if your command fits under an existing group before creating a top-level command:

• `cx alerts` - alert definitions + `schedulers`
• `cx notifications` - `connectors`, `routers`, `presets`, `test`
• `cx webhooks` - outgoing webhooks + `actions`
• `cx enrichments` - enrichment rules + `custom` enrichment tables
• `cx integrations` - integrations + `extensions`, `contextual-data`
• `cx iam` - `api-keys`, `roles`, `scopes`, `users`, `groups`, `ip-access`

Run `cx schema` to see the full command tree as JSON. 4. **Which archetype fits?**

| Archetype | When to use | Reference implementation | |-----------|------------|--------------------------| | **A: DataPrime-based** | Querying logs, spans, or any DataPrime source | `src/commands/logs/mod.rs` | | **B: REST-based** | Wrapping a Coralogix REST API (most new commands) | `src/commands/alerts/api.rs` + `src/commands/alerts/mod.rs` |

DataPrime commands delegate to a shared pipeline and require minimal code (~130 lines). REST commands build the full pipeline (API client, fan-out, merge, render) - more code but more control.

**Important:** All API integrations must use REST (HTTP). The CLI is HTTP-only by design - do not use gRPC.

Step 1: Read Reference Implementations

Before writing any code, read these files to internalize the existing patterns. This step is critical - agents that read existing code first produce implementations that are consistent with the codebase rather than inventing new patterns.

**Always read:**

• `src/main.rs` - study the `Commands` enum to see how variants are structured, and the `match cli.command` dispatch block to see where your new variant fits. Note which commands early-exit (no credentials needed) vs which go through the full config resolution flow. Pay attention to **wrapper groups** (e.g., `Notifications`, `Iam`, `Webhooks`, `Integrations`) - these are top-level commands with nested subcommand enums that group related domains. If your command belongs under an existing group, add a new variant to that group's subcommand enum rather than creating a top-level command.
• `src/commands/mod.rs` - see existing module registrations so you add yours in the right place
• `docs/adding-a-command.md` - full guide with code templates for both archetypes

**DataPrime archetype - also read:**

• `src/commands/logs/mod.rs` - a complete DataPrime command; notice how little code is needed because the shared pipeline does the heavy lifting
• `src/commands/dataprime/mod.rs` - the shared pipeline your command will delegate to; understand the `run_query()` signature and what it handles (fan-out, merge, spilling, agents output)

**REST archetype - also read:**

• `src/commands/alerts/api.rs` - see how response types are structured, how the API struct borrows `&CxClient`, how deserialization tests are written
• `src/commands/alerts/mod.rs` - see how the handler declares `pub mod api;` and imports types via `use api::{...};`
• `src/commands/dashboards/mod.rs` - see the fan-out/merge/render pattern using `render::*` helpers, and how all three output formats are handled

Step 2: Create API Layer (REST Only)

> Skip this step for DataPrime commands - they use the shared DataPrime pipeline.

Create `src/commands/<domain>/api.rs`. See `docs/adding-a-command.md` § "Archetype B, Step 1" for the full template.

Key conventions and why they matter:

• **`#[serde(rename_all = "camelCase")]`** on response types - Coralogix APIs use camelCase JSON keys
• **`#[serde(default)]` on `Vec` fields** - the API sometimes omits empty arrays entirely rather than sending `[]`, so this prevents deserialization failures
• **`Option<T>` for fields that may be absent** - be defensive, APIs evolve and fields vary across tiers
• **API struct borrows `&CxClient`** (don't own it) - the client is shared across the fan-out and must outlive individual API calls
• **`const BASE_PATH`** for the endpoint prefix - keeps URLs DRY
• **Deserialization tests are mandatory** - test both happy-path and edge cases (empty lists, missing optional fields) since these are the cases that break in production

Step 3: Create Command Module

Create `src/commands/<domain>/mod.rs`. For REST commands, declare `pub mod api;` at the top so the handler can `use api::{...};` types from its sibling `api.rs`. See `docs/adding-a-command.md` for full templates of both archetypes.

DataPrime archetype

Provide two things: 1. A text renderer: `pub fn render_<domain>_text(merged: &MergedResults) -> Result<()>` - called only for `OutputFormat::Text`; JSON and Agents output are handled by the