CLI Quickstart¶

The cxas command-line tool is your day-to-day companion for managing CX Agent Studio agents. This quickstart takes you through five practical tasks: discovering your Apps, pulling agent configs to disk, linting them for issues, pushing changes back to the platform, and running tool tests.

By the end, you'll understand the core pull → lint → edit → push workflow that most SCRAPI users follow.

Prerequisites¶

Before you start, make sure you have:

• SCRAPI installed: pip install cxas-scrapi
• Authentication configured (see Authentication)
• A GCP project with at least one CX Agent Studio App

Verify that the CLI is available:

cxas --help

You should see a list of available subcommands. If you see command not found, check that your virtual environment is activated and SCRAPI is installed.

Task 1 — Discover your Apps¶

Before you can work with an agent, you need to know what Apps exist in your project. Use cxas apps list to see them:

cxas apps list --project-id my-gcp-project --location us

Example output:

Apps:
 Display Name                  Name
 My Customer Service Bot       projects/my-gcp-project/locations/us/apps/abc123
 Internal HR Assistant         projects/my-gcp-project/locations/us/apps/def456

If you already know the app's display name and want its details:

cxas apps get --project-id my-gcp-project --location us app-name

Task 2 — Pull an App's configuration¶

Once you know your App ID, use cxas pull to download the agent configuration to your local machine:

cxas pull projects/my-gcp-project/locations/us/apps/abc123

This creates a local directory structure that mirrors the agent's configuration on the platform:

./My_Customer_Service_Bot/
├── app.json
├── agents/
│   └── main-agent/
│       ├── main-agent.json
│       └── instruction.txt
├── tools/
│   └── check_order_status/
│       └── check_order_status.json
└── guardrails/

Each JSON file represents a resource from the platform. This is your local "source of truth" — the files you'll edit, lint, version control, and push back.

Change into the exported app directory containing app.json before continuing. Use the directory name created by your export.

Task 3 — Lint your configuration¶

Before making any changes (or as part of your CI pipeline), run the linter to check the pulled configuration against SCRAPI's 60+ best-practice rules:

cxas lint

SCRAPI looks for an optional cxaslint.yaml file in your current directory to find the agent configs to lint. Pull does not create this file. If you're in the directory created by cxas pull, it should just work.

Example output (clean):

Linting agent configuration...
============================================================
Lint Results
============================================================
  No issues found! Your configuration looks great.
============================================================

Example output (with issues):

Linting agent configuration...
============================================================
Lint Results
============================================================
  [WARNING] tools/check_order_status/python_function/python_code.py [T002] Tool is missing a docstring.
  [ERROR]   agents/main-agent/instruction.txt [I001] Missing required XML tag: <role>.
============================================================
2 issues found (1 error, 1 warning)

Errors (marked [ERROR]) indicate things you should fix before pushing. Warnings are gentler suggestions worth reviewing.

Task 4 — Make a change and push¶

Let's say you want to update a tool description. Open the relevant JSON file and edit the description, keeping the other fields:

{
  "displayName": "Check Order Status",
  "description": "Looks up the current status and estimated delivery date for a given order ID."
}

Once you're happy with your changes, run the linter one more time to make sure everything is clean:

cxas lint

Then push the changes back to the platform:

cxas push --to projects/my-gcp-project/locations/us/apps/abc123

Example output:

Pushing app from ....
Pushing to existing app... Overwriting if supported.
Uploading to CES...
Waiting for import to complete...
Successfully pushed to: projects/my-gcp-project/locations/us/apps/abc123

Your changes are now live on the platform.

Task 5 — Run tool tests¶

After pushing changes, use cxas test-tools to verify that your tools behave correctly:

cxas test-tools --app-name projects/my-gcp-project/locations/us/apps/abc123 --test-file tests/tool_tests.yaml

Use the path to your local tool test file. This runs your tool evaluation test cases against the live platform and reports the results:

Example output:

Running tool tests for App: projects/my-gcp-project/locations/us/apps/abc123

  [PASS] check_order_status: basic lookup
  [PASS] check_order_status: invalid order ID returns error
  [PASS] lookup_customer: returns customer record
  [FAIL] lookup_customer: handles missing email gracefully

============================================================
Results: 3 passed, 1 failed
============================================================

If any tests fail, the output will include details about what was expected versus what was returned, making it easier to diagnose the issue.

The full workflow at a glance¶

Here's the complete pull → lint → edit → push → test loop:

# 1. See your Apps
cxas apps list --project-id my-project --location us

# 2. Pull configuration locally
cxas pull projects/my-project/locations/us/apps/abc123

# Use the exported app directory (replace with its actual name)
cd My_Customer_Service_Bot

# 3. Check for issues
cxas lint

# 4. ... edit your JSON files ...

# 5. Lint again to confirm all clear
cxas lint

# 6. Push to platform
cxas push --to projects/my-project/locations/us/apps/abc123

# 7. Run tests
cxas test-tools --app-name projects/my-project/locations/us/apps/abc123 --test-file tests/tool_tests.yaml

Other commands worth knowing¶

What's next?¶

• Read the CLI Reference for full documentation of every command and flag
• Learn about the Key Concepts behind Apps, Agents, and the resource hierarchy
• Set up AI Skills for AI-assisted agent development
• Explore the Linting Guide to customize your lint rules