## Context
`cx incidents list` was producing frequent 400s because the v5 list
endpoint expects repeated filter fields, fully qualified incident enum
values, and paginated request/response shapes. The CLI was sending
several filters as scalar strings and did not bound or paginate list
responses, which made both API errors and oversized responses likely.
## Linked Issues
https://linear.app/coralogix/issue/AIAPP-1882/fix-incidents-list-endpoint
## Design
The list command now builds a typed `ListIncidentsOptions` object from
clap arguments, converts that into the v5 JSON request body in one
helper, and loops through `pagination.nextPageToken` until the requested
limit is reached. The API layer accepts the v5 `pagination` response
while retaining compatibility with older top-level `nextPageToken`.
Rendering stays unchanged after the command has accumulated incidents
across selected profiles.
## Key Decisions
The CLI accepts short user-facing values such as `CRITICAL`,
`TRIGGERED`, and `created_at`, then normalizes them to v5 enum values
like `INCIDENT_SEVERITY_CRITICAL`, `INCIDENT_STATUS_TRIGGERED`, and
`INCIDENTS_FIELDS_CREATED_TIME`. Results are bounded to `--limit 100` by
default to avoid unexpectedly large payloads; callers can opt into
`--all` when they deliberately need every page. When every selected
profile fails, list now exits nonzero instead of silently returning an
empty result, since the previous behavior hid live API failures.
## Changes
- Changes `cx incidents list` filters from scalar request fields to v5
repeated fields for status, severity, state, assignee, application, and
subsystem filters.
- Adds list flags for state, application/subsystem, contextual labels,
query targeting, muted/unmuted, created and duration ranges, ordering,
page size/token, bounded limits, and explicit `--all` pagination.
- Parses v5 pagination responses and fetches additional pages up to the
requested limit.
- Validates contextual labels and `--query` target selection before
sending malformed requests.
- Updates incident-management skill guidance to recommend bounded
queries and the supported filter set.
- Extends ignored live e2e coverage and adds a wiremock integration test
for request shape and pagination.
## Testing
- `cargo test --lib incidents --locked`
- `cargo test --test incidents --locked`
- `cargo test incidents --locked`
- `cargo test --test e2e incidents --locked`
- `cargo test --test e2e incidents --locked -- --ignored --nocapture`
- `cargo fmt --check`
- `cargo clippy --locked -- -D warnings`
- Manual live checks with `target/debug/cx incidents list` covering:
`--limit`, status/severity filters, state filter, created range plus
ordering, muted/unmuted, app/subsystem, contextual labels, repeated
status/severity, duration range, and pagination across pages.
- Manual live search checks: contextual-label search and some
`searchQuery.incidentField` values succeeded without 400s; `ID` and
`SEVERITY` incident-field search returned v5 server 500s.
## Risks & Rollout
This changes the public `cx incidents list` interface by making existing
`--status`, `--severity`, and `--assignee` repeatable while preserving
single-use invocations. The default result set is now bounded to 100
incidents, which is safer for agents but may return fewer rows than
before for users who expected an unbounded first response; `--all`
restores full pagination. Rollback is the single commit if the v5
request shape causes unexpected compatibility issues.
## Out of Scope / Follow-ups
Grouping global help options is intentionally left for a separate task.
v5 incident search has server-side inconsistencies: the OpenAPI schema
says `searchQuery.field` is required, the live endpoint rejects that
field, and `searchQuery.incidentField` with `ID` or `SEVERITY` returns
500. This PR avoids known malformed no-target search requests but does
not attempt to work around those server-side search failures.
## Summary
Three doc fixes based on customer report and portal QA.
### 1. DataPrime string quoting in shell examples
Shell examples use double quotes for DataPrime string literals, but
DataPrime only accepts single quotes. Running the examples as written
produces:
```
error from profile 'default': API request failed (400): Compilation errors:
- malformed expression at [0:22:22-0:23:23]: `"`
- excessive input at [0:28:28-0:29:29]: `"`
```
- Severity comparisons: remove quotes — `ERROR`, `INFO`, etc. are enum
values in DataPrime and don't need quoting
- String comparisons (e.g. `serviceName`): switch to double-quoted outer
shell arg with escaped `$` and single-quoted DataPrime string literal
### 2. `<details open>` → `<details open markdown="1">`
MkDocs Material requires `markdown="1"` on `<details>` elements to
render Markdown content inside them correctly.
### 3. Fix 404 on `skills/README.md` link
The relative `skills/README.md` link in the AI agent skills section
resolves correctly on GitHub but 404s on the Coralogix docs portal (the
`skills/` directory is not synced). Changed to an absolute GitHub URL.
**Files changed:** `README.md`, `docs/multi-profile.md`,
`docs/time-syntax.md`
Reported via Coralogix support (DOCS-23).
Jakub Majak