Cx Infra

Infrastructure Resources Skill

Use this skill to discover and inspect infrastructure resources — what exists, whether it is healthy, and what its raw data contains.

CLI Commands

• All commands are read-only and support -o json / -o toon for structured output.
• Multi-profile fan-out applies to `types`, `filters` and `list` only. Repeat -p <profile> on those to compare fleets across accounts. health-history and raw-data take a resource id, which is scoped to one team, so they reject more than one -p — run them once per profile instead.
• Filtering takes two flags. Every --match-all must match; at least one --match-any must match; the two groups combine with AND. So --match-all OS=linux --match-any Health=Critical --match-any Region=eu-west-1 means OS=linux AND (Health=Critical OR Region=eu-west-1).
• A comma lists several values for one attribute, and the flag decides what that means. In --match-any they are alternatives — any one matches: --match-any Region=eu-west-1,us-east-2. In --match-all every one must match, which is how to narrow on two substrings at once: --match-all 'Name=*alert*,*processing*' finds the names holding both. An attribute that carries a single value cannot equal two of them, so for either value, reach for --match-any.
• An attribute belongs to exactly one flag. Repeating it within a flag, or naming it in both, is refused — list its values after the comma instead.
• Nothing is required except one narrowing input. --category and --type are ordinary filters, not prerequisites, so --match-all Health=Critical alone works. A request naming none of --match-all, --match-any, --category or --type is rejected.
• `Category` and `Type` are not filterable attributes. They select which resource types a request covers, have their own flags, and never appear in filters output — so there is no --match-all Category=Hosts, use --category Hosts.
• An exact value is case-sensitive; a wildcard one is not. OS=linux matches and OS=Linux returns nothing, but Name=*checkout* and Name=*Checkout* are the same query. filters lists values only for a fixed set, so for free text either take the spelling from a row's columns or use a wildcard. A status value is matched case-insensitively either way.
• 0 rows is an answer, not a failure. A valid attribute that is simply unpopulated matches nothing; do not retry or reword the query. A misspelled attribute or an out-of-set value is rejected outright, naming what is accepted.
• `filters` tells you three things per attribute. kind is what the value looks like — string means free text, status means a fixed set, and number, bool and date mean themselves. values lists the accepted values of a fixed set — pass one of those, spelled as filters reports it. wildcard says whether a * is accepted in the value — only string attributes accept one, and it matches anywhere in the value: --match-all 'Name=*checkout*' — quote it, or the shell expands the *.
• `--name-filter` and `--scope` are the legacy flags and stand apart. Both require --category and --type, and neither can be combined with --match-all or --match-any. Use --scope to narrow by service, environment or team; use the filter flags for everything else — --match-all 'Name=*web*' is the same query as --name-filter web.
• Pagination: --start-row / --end-row define a row window (--end-row is exclusive); the default is the first 100 rows, and omitting only --end-row gives 100 rows from --start-row. Page through large fleets in windows (0-100, 100-200, …). `list` never pages for you — fleets can run to hundreds of thousands of resources, so it returns one window and reports the total.
• The window cannot reach past row 10,000. The API rejects any request whose start-row + rows exceeds 10,000, so paging cannot enumerate a fleet larger than that even though total_count reports its true size. In any case, narrow until the result fits — add --match-all attributes, or a --type — and page within each subset rather than trying to walk the whole list.
• list wraps its rows in an envelope (total_count, returned_count, resources) — the other subcommands return bare arrays. total_count is the fleet-wide match count, independent of the window. Check it before reasoning over the rows: keep paging while start_row + returned_count < total_count, and if it exceeds what you can page to, narrow the query rather than trusting a partial answer.
• Pass resource IDs exactly as returned by `list` (quote them — they contain : and =); the CLI percent-encodes them for you.

Inspection Workflow

Three steps, and only because each one supplies an input the next one requires: filters gives the attribute names and their accepted values, list gives the resource_id. Answering "is web-server-1 healthy?" is these three calls — nothing more.

1. Discover what can be filtered — attribute names and their accepted values are per resource type and dynamic, so never guess. Omit both flags for the union across every type:

   cx infra resources filters -o json

cx infra resources types -o json lists the (category, type) pairs, when you need those rather than the attributes.

1. List resources, narrowing by any attribute filters offered:

   cx infra resources list --category Hosts --type EC2_Instances \
     --match-all Health=Critical -o json

1. Inspect one resource using a resource_id from step 2. Statuses are Healthy, Critical, or Unmonitored, one sample per day, oldest first:

   cx infra resources health-history "1001234:host_id=i-abc123" -o json

raw-data is the alternative to this step, not a follow-on — use it instead when you need source-specific detail rather than health.

Examples

Unhealthy hosts in one region

# Health is a fixed set, so `filters` first for the accepted values
cx infra resources filters --category Hosts -o json | jq '.[] | select(.name == "Health")'

cx infra resources list --category Hosts \
  --match-all Health=Critical --match-all Region=eu-west-1 -o json \
  | jq '.resources[] | {name, type}'

Every resource whose name contains a substring

# `filters` reports wildcard: true for Name, so `*` is accepted
cx infra resources list --match-all 'Name=*checkout*' -o json \
  | jq '.resources[] | {name, category, type}'

Either of two attributes, any resource type

# --match-any ORs across attributes; no category or type needed
cx infra resources list \
  --match-any Name=coredns --match-any Namespace=kube-system -o json \
  | jq '.resources[] | {name, category, type}'

# Two values of the *same* attribute take the comma form, not a second flag
cx infra resources list --match-any Namespace=kube-system,observability -o json

# The same comma in --match-all requires *all* the values: names holding both
cx infra resources list --match-all 'Name=*alert*,*processing*' -o json

Just the ids and names