add-command
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.
coralogix · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add coralogix/cx-cli --skill add-command技能说明
name: add-command description: Use this skill when the user asks to "add a command", "implement cx ", "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:
- 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.
- What should the user be able to do? List the subcommands (e.g.,
list,get,create) and what flags make sense. - 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 +schedulerscx notifications-connectors,routers,presets,testcx webhooks- outgoing webhooks +actionscx enrichments- enrichment rules +customenrichment tablescx integrations- integrations +extensions,contextual-datacx iam-api-keys,roles,scopes,users,groups,ip-accessRuncx schemato see the full command tree as JSON.
- 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 theCommandsenum to see how variants are structured, and thematch cli.commanddispatch 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 placedocs/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 liftingsrc/commands/dataprime/mod.rs- the shared pipeline your command will delegate to; understand therun_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 writtensrc/commands/alerts/mod.rs- see how the handler declarespub mod api;and imports types viause api::{...};src/commands/dashboards/mod.rs- see the fan-out/merge/render pattern usingrender::*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)]onVecfields - the API sometimes omits empty arrays entirely rather than sending[], so this prevents deserialization failuresOption<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_PATHfor 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:
- A text renderer:
pub fn render_<domain>_text(merged: &MergedResults) -> Result<()>- called only forOutputFormat::Text; JSON and Agents output are handled by the