vais — Vertex AI Search for Commerce CLI

!!! WARNING: This is only proof of concept. It works as of 09.04.2026 but is not maintained !!!

A CLI tool to back up and restore configuration of Vertex AI Search for Commerce (Retail API) on Google Cloud Platform.

---

What it does

vais lets you snapshot your Vertex AI Search for Commerce configuration to JSON files, and restore it later. Use it to:

• Back up config before a change
• Migrate config between environments (dev → staging → prod)
• Review config changes via git diff
• Restore after an accidental change

---

Resources managed

Resource	API resource	Description
serving-configs	servingConfigs	Search/recommendation tuning
controls	controls	Boost, filter, redirect, synonym rules
catalog-attributes	attributesConfig	How product attributes are indexed
models	models	Recommendation model configurations
completion-config	completionConfig	Autocomplete / query suggestion settings

---

Prerequisites

• Python 3.12+
• gcloud CLI installed and authenticated: gcloud auth application-default login
• A GCP project with the Retail API enabled

---

Installation

pip install -r requirements.txt

---

Configuration

Configure via flags or environment variables:

Flag	Env var	Default	Description
--project	GOOGLE_CLOUD_PROJECT	required	GCP project ID
--location	VAIS_LOCATION	global	Retail API location
--catalog	VAIS_CATALOG	default_catalog	Catalog name
--output-dir	VAIS_OUTPUT_DIR	./backups	Local backup directory

Recommended: create a .env file or export variables in your shell:

export GOOGLE_CLOUD_PROJECT=my-gcp-project

---

Usage

Read (GCP → local JSON files)

Download all resources:

python vais.py read --project my-gcp-project

Download a specific resource:

python vais.py read serving-configs --project my-gcp-project
python vais.py read controls --project my-gcp-project
python vais.py read catalog-attributes --project my-gcp-project
python vais.py read models --project my-gcp-project
python vais.py read completion-config --project my-gcp-project

Write (local JSON files → GCP)

Restore all resources:

python vais.py write --project my-gcp-project

Restore a specific resource:

python vais.py write serving-configs --project my-gcp-project
python vais.py write controls --project my-gcp-project

Resources already matching the local config are skipped ("up to date"). Resources that differ prompt for confirmation unless --force is passed:

python vais.py write --project my-gcp-project --force

---

Backup file layout

backups/
  serving-configs/
    default-search.json
    recommendation-pdp.json
  controls/
    boost-sale-items.json
    redirect-homepage.json
  catalog-attributes/
    attributes.json         # single file — API returns one object
  models/
    recently-viewed.json
  completion-config/
    default.json            # single file — API returns one object

Files are plain JSON — safe to commit to git. Add backups/ to your repo to track config over time.

---

Typical workflows

Backup before a change

python vais.py read --project my-gcp-project
git add backups/ && git commit -m "backup: pre-change snapshot"

Migrate config from staging to prod

# In staging dir:
python vais.py read --project staging-project

# Copy backups/ to prod dir, then:
python vais.py write --project prod-project

Review what changed

python vais.py read --project my-gcp-project
git diff backups/

---

Development

pip install -r requirements.txt
python vais.py --help

Project structure

vais/
  vais.py                     # CLI entry point
  requirements.txt
  README.md
  tasks/                      # agent task definitions
  backups/                    # local JSON snapshots (git-trackable)
  src/
    client.py                 # Retail API client wrapper + auth
    config.py                 # project/catalog settings
    diff.py                   # idempotency check (local vs remote)
    io.py                     # JSON file read/write helpers
    resources/
      serving_configs.py
      controls.py
      catalog_attributes.py
      models.py
      completion_config.py