Skip to content

cxas insights

cxas insights gives you programmatic access to QA scorecards in the CX Agent Studio Insights API — you can list, export, import, and copy scorecards without ever leaving your terminal.

Usage

cxas insights <subcommand> [options]

Subcommands

Subcommand Description
list-scorecards List all QA scorecards under a project and location.
export-scorecard-from-insights Export a scorecard and its questions to a local JSON or YAML file.
import-scorecard-to-insights Import a scorecard template file into Insights as a new revision.
copy-scorecard Copy a scorecard's questions into another scorecard.

list-scorecards

Lists all QA scorecards in the specified project and location.

Options

Option Required Default Description
--parent PARENT Yes — Parent resource name in the format projects/{project}/locations/{location}.

Example

cxas insights list-scorecards \
  --parent "projects/my-gcp-project/locations/us-central1"

Output:

Scorecard: projects/my-gcp-project/locations/us-central1/qaScorecards/sc-001 (Customer Satisfaction)
Scorecard: projects/my-gcp-project/locations/us-central1/qaScorecards/sc-002 (Agent Quality)

export-scorecard-from-insights

Exports a scorecard and all its questions from the Insights API to a local JSON or YAML template file, so you can version-control it or use it as a base for other scorecards.

Options

Option Required Default Description
--scorecard-name NAME Yes — Full resource name of the scorecard to export (e.g., projects/{project}/locations/{location}/qaScorecards/{id}).
--template PATH Yes — Local file path to write the template to. Use a .json or .yaml extension.

Example

cxas insights export-scorecard-from-insights \
  --scorecard-name "projects/my-gcp-project/locations/us-central1/qaScorecards/sc-001" \
  --template ./scorecards/customer-satisfaction.json

The exported file captures the scorecard metadata and the full list of questions with their types, choices, instructions, and ordering.

import-scorecard-to-insights

Reads a scorecard template file and imports it into the Insights API, either creating a new revision of an existing scorecard or creating a brand-new scorecard under a parent.

Options

Option Required Default Description
--template PATH Yes — Path to the local scorecard template file (.json or .yaml).
--scorecard-name NAME No* — Full resource name of an existing scorecard to update with a new revision.
--parent PARENT No* — Parent resource name (projects/{project}/locations/{location}) to create a brand-new scorecard under.

*Provide either --scorecard-name (to update) or --parent (to create new).

Examples

Import as a new revision of an existing scorecard:

cxas insights import-scorecard-to-insights \
  --template ./scorecards/customer-satisfaction.json \
  --scorecard-name "projects/my-gcp-project/locations/us-central1/qaScorecards/sc-001"

Import as a brand-new scorecard:

cxas insights import-scorecard-to-insights \
  --template ./scorecards/new-scorecard.yaml \
  --parent "projects/my-gcp-project/locations/us-central1"

copy-scorecard

Copies all questions from one scorecard into another — useful for replicating a well-tuned scorecard into a new project or environment.

Options

Option Required Default Description
--scorecard-name NAME Yes — Full resource name of the source scorecard to copy from.
--dst-scorecard-name NAME No* — Full resource name of the destination scorecard to overwrite.
--parent PARENT No* — Parent resource name to create a brand-new scorecard as the destination.

*Provide either --dst-scorecard-name (to copy into an existing scorecard) or --parent (to create a new one).

Examples

Copy a scorecard into an existing destination:

cxas insights copy-scorecard \
  --scorecard-name "projects/my-gcp-project/locations/us-central1/qaScorecards/sc-001" \
  --dst-scorecard-name "projects/my-other-project/locations/us-central1/qaScorecards/sc-010"

Copy and create a new scorecard in a different project:

cxas insights copy-scorecard \
  --scorecard-name "projects/my-gcp-project/locations/us-central1/qaScorecards/sc-001" \
  --parent "projects/my-other-project/locations/us-central1"
  • cxas export — Export agent evaluation definitions (not scorecards).
  • cxas run — Run evaluations against a deployed app.