Add Command

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?

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 shared pipeline
2. A thin run() wrapper that calls super::dataprime::run_query() with your DataPrime source name