Home CLI guides Index Advisor CLI

Index Advisor CLI

Last updated on Jul 12, 2026

Current Status

Index Advisor has a deterministic local-file CLI command group for CI/support automation. It does not call Firebase, sync remote indexes, create indexes, or deploy index files. Those write-like or live remote workflows remain GUI/live verification work and must require explicit project approval if added later.

All successful commands emit JSON.

Commands

index-advisor analyze

Analyze a query shape against local Firestore index JSON:

index-advisor analyze \
  --collection users \
  --where-fields status,region \
  --order-by "createdAt desc" \
  --indexes firestore.indexes.json

You can also pass a query-shape file:

index-advisor analyze \
  --query-shape query-shape.json \
  --indexes firestore.indexes.json \
  --error-file firestore-error.log

Supported query-shape JSON fields:

  • collectionPath
  • whereFields
  • orderByClauses with fieldPath and optional direction
  • orderByFields as a shorthand array when direction does not matter

The JSON response includes:

  • queryShape.collectionGroup
  • loaded indexes
  • report.requiredFields
  • report.hasMatchingIndex
  • report.matchingIndexes
  • report.missingFields
  • report.warnings.proactive
  • report.warnings.cost
  • report.suggestedIndexJSON
  • report.suggestedIndexSpec
  • optional report.indexCreationURL
  • deterministic logs and explanations

Matching is order-sensitive. The analyzer treats a candidate index as covered only when the required query fields match the composite index prefix and any orderBy directions match. A candidate with the right fields in the wrong order returns hasMatchingIndex: false, emits an order/direction mismatch log, and keeps the deterministic suggested index output.

index-advisor parse-error

Extract a Firebase Console index creation URL from captured Firestore error text:

index-advisor parse-error --file firestore-error.log
index-advisor parse-error --text "FAILED_PRECONDITION: ..."

The response includes found, indexCreationURL, and logs.

index-advisor load-indexes

Parse local Firestore index JSON and return the normalized index definitions:

index-advisor load-indexes --file firestore.indexes.json

This is useful in CI to validate that the index file is parseable before using it in index-advisor analyze.

Selected Module Dispatch

index-advisor can be selected as the active module:

module select index-advisor
run parse-error --file firestore-error.log

Not Yet Covered by CLI

  • Remote index sync from a live Firebase project.
  • Index creation or deploy.
  • Opening Firebase Console from the terminal.
  • AI explanations beyond deterministic service output.

Any future live sync or write-like behavior must label the target project and environment, refuse read-only projects where applicable, require explicit confirmation for production changes, and include approved live verification evidence.

Source Anchors

  • Sources/FirestructCore/IndexAdvisorService.swift
  • Sources/FirestructCore/FirestoreIndexCreationLinkSummary.swift
  • Sources/FirestructCLIKit/IndexAdvisorCommand.swift
  • Tests/FirestructCLIIntegrationTests/FirestructCLIIntegrationTests.swift