CLI Reference¶

The cxas CLI puts the full power of CX Agent Studio in your terminal — you can pull apps, push changes, run evaluations, lint your configs, spin up GitHub Actions, and a whole lot more, all without touching the Cloud Console.

Global Options¶

These options apply to every cxas command:

Option	Required	Default	Description
`--oauth-token TOKEN`	No	—	OAuth bearer token for authenticating with the CES API. If omitted, the CLI falls back to `CXAS_OAUTH_TOKEN` and then to Application Default Credentials.

Environment Variables¶

Variable	Description
`CXAS_OAUTH_TOKEN`	OAuth bearer token. Set this instead of passing `--oauth-token` on every command.
`GOOGLE_APPLICATION_CREDENTIALS`	Path to a service account key file. Used as a fallback when no OAuth token is present, following standard Google Cloud ADC behaviour.

Resource Identifier Format¶

Most commands that target a specific app accept either a full resource name or a display name. The full resource name follows this pattern:

projects/{project}/locations/{location}/apps/{app}

For example:

projects/my-gcp-project/locations/us-central1/apps/my-agent-app

When you pass a display name (e.g., "My Support Agent") instead of a resource name, you also need to provide --project-id and --location so the CLI can look it up.

Commands¶

Command	Description
`cxas pull`	Export an app from CX Agent Studio to a local directory.
`cxas push`	Upload a local agent directory back to CX Agent Studio.
`cxas create`	Create a brand-new app in CX Agent Studio.
`cxas delete`	Permanently delete an app.
`cxas branch`	Clone an existing app into a new one (pull → create → push).
`cxas apps`	List all apps or get details about a specific one.
`cxas export`	Export an evaluation definition to a YAML or JSON file.
`cxas push-eval`	Upload evaluation definitions from a YAML file to an app.
`cxas run`	Trigger evaluations and optionally wait for results.
`cxas test-tools`	Run unit tests against your agent's tools.
`cxas test-callbacks`	Run unit tests for all callbacks in an app directory.
`cxas test-single-callback`	Run unit tests for a single, specific callback.
`cxas ci-test`	Run the full CI test lifecycle against a temporary app.
`cxas local-test`	Run the CI test lifecycle inside a local Docker container.
`cxas init-github-action`	Generate a GitHub Actions workflow file for your agent.
`cxas lint`	Lint your app directory for best-practice violations.
`cxas init`	Bootstrap a project with AI agent development skills.
`cxas insights`	Manage QA scorecards via the Insights API.