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

Command	Purpose	Key flags
cx infra resources types	List available resource types (category/type pairs)	-
cx infra resources list	List resources of one category/type	--category, --type (required); --name-filter, --scope key=value, --start-row, --end-row
cx infra resources health-history <resource-id>	Daily health samples for one resource, oldest first	-
cx infra resources raw-data <resource-id>	Raw resource document as JSON	-

• All commands are read-only and support -o json / -o toon for
  structured output.
• Multi-profile fan-out applies to types 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.
• --scope is repeatable across different keys; allowed keys are service,
  environment, team (e.g. --scope environment=prod --scope service=checkout).
  Multiple keys combine with AND — a resource must match all of them. Each key
  accepts a single value and may be given at most once; repeating one (e.g.
  --scope service=a --scope service=b) is rejected. To cover several values for one key, run one query per
  value and combine the results.
• 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 with --name-filter or --scope 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, always present and independent of the window, so use it
  as the stop condition: keep paging while start_row + returned_count < total_count, subject to the 10,000-row ceiling above.
• 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:
types gives the mandatory --category/--type, list gives the resource_id.
Answering "is web-server-1 healthy?" is these three calls — nothing more.

1. Discover what exists — categories and types are dynamic, so never guess:

   cx infra resources types -o json
   

2. List resources of that category/type, narrowing with name and scope filters:

   cx infra resources list --category Hosts --type EC2_Instances \
     --name-filter web --scope environment=prod -o json
   

3. 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

Just the ids and names

# Rows live under .resources — `list` returns an envelope
cx infra resources list --category Hosts --type EC2_Instances -o json \
  | jq '[.resources[] | {resource_id, name}]'

Check fleet size, and whether one window covered it

cx infra resources list --category Hosts --type EC2_Instances -o json \
  | jq '{total_count, returned_count}'

# Next window, if there is one
cx infra resources list --category Hosts --type EC2_Instances \
  --start-row 100 --end-row 200 -o json

Find when a resource went critical

# health-history returns a bare array, so no .resources here
cx infra resources health-history "1001234:host_id=i-abc123" -o json \
  | jq '[.[] | select(.status == "Critical")]'

Read the raw resource document

# Source-specific detail: tags, instance metadata, configuration
cx infra resources raw-data "1001234:host_id=i-abc123" -o json

Key Principles

• Discover before listing — --category and --type are required;
  always start from cx infra resources types.
• Quote resource IDs and pass them verbatim — they embed :, |, and =;
  the CLI handles URL encoding.
• Scope keys are a fixed set (service, environment, team) — unknown
  keys are rejected client-side before any request is made.
• A missing raw document is not an error — raw-data exits 0 and emits an
  empty result on stdout: [] in json, [0]: in agents, and
  No raw data found. in text. Only the note no raw data for this resource goes
  to stderr. Parse the empty stdout result as a cleanly absent document, not a
  failure — and do not expect stdout to be blank.
• Use -o json with jq for filtering; use -o toon for token-efficient
  output in agent contexts.
• Multi-profile fan-out is for types and list only — repeating
  -p <profile> tags each row with its profile so fleets can be compared across
  accounts. The row window applies per profile, so list adds a
  counts_by_profile breakdown — page each profile against its own total_count,
  not the aggregate. health-history and raw-data error on a second -p.
• A resource id never crosses profiles — it embeds the team id
  (1001234:host_id=…), so an id from one account cannot resolve in another. When
  a multi-profile list turns up something worth inspecting, note its profile
  field and query that single profile for its health or raw data.
• Infra health is its own concept — the Healthy/Critical/Unmonitored
  statuses are computed by the infrastructure domain and are not the same as
  Service Catalog health. Correlate them with telemetry signals;
  do not treat them as interchangeable.
• resource_id never leaves this skill — pass it only to health-history
  and raw-data. For every other command, pivot on the resource name or the
  service scope value.

Related Skills

Bridge to these skills using the resource name or the service scope
value — never the resource id, which only this skill understands:

• cx-telemetry-querying — cx search-fields "<name>" -s value discovers
  which log/span fields contain the resource name; cx logs "filter $l.subsystemname == '<service>'" queries the service's telemetry. Correlate a
  Critical health day with error logs or CPU metrics.
• cx-alerts — cx alerts list --name "<name-or-service>" finds alert
  definitions matching the resource or its service by substring.
• cx-dashboards — cx dashboards search "<name-or-service> ..." and
  cx dashboards query-search --description "..." find dashboards semantically;
  pair with search-fields -s value to then query-search --field the exact
  field holding the resource name.