Skip to content

cxas push

cxas push uploads a local agent directory to CX Agent Studio, either updating an existing app or creating a fresh one — it's how your local edits make it into the platform.

Usage

cxas push [--app-dir DIR] [--to TARGET] [--env-file FILE]
          [--app-name APP] [--display-name NAME]
          --project-id PROJECT --location LOCATION

Options

Option Required Default Description
--app-dir DIR No . (current directory) Path to the local agent directory to upload.
--to TARGET No — Target app to overwrite. Accepts a full resource name or display name. When provided, the existing app is updated in place.
--env-file FILE No — Path to a JSON environment file to inject as environment.json before uploading. Useful for supplying environment-specific secrets or variables without committing them.
--app-name APP No — Explicit app resource name to push to (v1beta API). Use this when you want to overwrite a specific app and already know its full ID.
--display-name NAME No "Pushed Agent" Display name for the new app when no target is specified and a new app will be created.
--project-id PROJECT Yes — GCP project ID.
--location LOCATION Yes — GCP location (e.g., global, us-central1).

What Gets Uploaded

The CLI bundles the following top-level items from --app-dir into a ZIP archive before uploading:

  • app.yaml / app.json
  • global_instruction.txt
  • environment.json (or the file you pass via --env-file)
  • agents/, tools/, guardrails/, toolsets/
  • evaluations/, evaluationDatasets/, evaluationExpectations/
  • .github/workflows/

Everything else in the directory (e.g. .git, local test output) is ignored.

Examples

Push the current directory to an existing app by display name:

cxas push \
  --to "My Support Agent" \
  --project-id my-gcp-project \
  --location us-central1

Push a specific directory and create a new app with a custom display name:

cxas push \
  --app-dir ./my-agent \
  --display-name "My Support Agent (Staging)" \
  --project-id my-gcp-project \
  --location us-central1

Push using a separate environment file (keeps secrets out of source control):

cxas push \
  --app-dir ./my-agent \
  --to projects/my-gcp-project/locations/us-central1/apps/abc123 \
  --env-file ./secrets/env-prod.json \
  --project-id my-gcp-project \
  --location us-central1
  • cxas pull — Download an app to a local directory first.
  • cxas create — Create an empty app shell before pushing.
  • cxas ci-test — Run the full push + test lifecycle in CI.