gcloud / bq / Python / ADK / agents-cli

Google Command Quick Reference

Google Cloud commands for authentication, agent development, AI hosting and data workflows.

Reference only; nothing runs here. Commands use your permissions and may change resources or incur charges in your own terminal. Bash syntax shown.

Install Google Cloud CLIDocument AI Python example

Your terminal environment

Enter your existing project ID, a supported region and an existing bucket name when prompted. These variables apply only to your terminal session; this block creates no Cloud resources.

read -r -p "Google Cloud project ID: " PROJECT_ID
read -r -p "Google Cloud region (e.g. us-central1): " REGION
read -r -p "Existing bucket name (without gs://): " BUCKET_NAME
export PROJECT_ID REGION BUCKET_NAME

Document AI’s processor location is separate from REGION. Use the location returned for your processor and its matching regional endpoint.

57 / 57 commands

Setup & auth

Read

Check CLI installation

Display installed Google Cloud CLI versions.

TERMINAL / BASH
gcloud version

Install the Google Cloud CLI first; Cloud Shell already includes it.

Official reference

Setup & auth

Local setup

Sign in to the CLI

Authorize gcloud to act as your Google account.

TERMINAL / BASH
gcloud auth login

This does not configure Application Default Credentials for Python libraries. Avoid shared terminals.

Official reference

Setup & auth

Read

Inspect active accounts

List CLI accounts and the active identity.

TERMINAL / BASH
gcloud auth list

Account emails are sensitive; do not share terminal output publicly.

Official reference

Setup & auth

Local setup

Authenticate local Python

Create local Application Default Credentials for Google Cloud client libraries.

TERMINAL / BASH
gcloud auth application-default login

For local development only. Deployed workloads should use an attached service identity or federation, not downloaded keys.

Official reference

Setup & auth

Local setup

Set ADC quota project

Select the project used for supported API quota and billing attribution by local ADC.

TERMINAL / BASH
gcloud auth application-default set-quota-project "$PROJECT_ID"

Requires serviceusage.services.use on this project; this does not grant service-specific permissions.

Official reference

Setup & auth

Read

Inspect configuration

Review the current project, account and configured properties.

TERMINAL / BASH
gcloud config list

Commands with explicit --project or --region override defaults.

Official reference

Projects & APIs

Local setup

Set default project

Select the default project for subsequent gcloud commands.

TERMINAL / BASH
gcloud config set project "$PROJECT_ID"

Check the project ID before any command that changes resources or incurs charges.

Official reference

Projects & APIs

Local setup

Set Cloud Run region

Set the default region for Cloud Run commands.

TERMINAL / BASH
gcloud config set run/region "$REGION"

There is no universal region property: Vertex AI commands below specify --region explicitly. Document AI uses its processor location.

Official reference

Projects & APIs

Read

List accessible projects

List projects visible to the active identity.

TERMINAL / BASH
gcloud projects list

Visibility depends on your permissions; missing projects may still exist.

Official reference

Projects & APIs

Read

List enabled APIs

Inspect APIs currently enabled for your project.

TERMINAL / BASH
gcloud services list --enabled --project="$PROJECT_ID"

Enabling an API does not create a processor, model or bucket.

Official reference

Projects & APIs

Cloud change

Enable AI and data APIs

Enable the services used by the portal’s Google Cloud learning examples.

TERMINAL / BASH
gcloud services enable documentai.googleapis.com vision.googleapis.com aiplatform.googleapis.com bigquery.googleapis.com storage.googleapis.com --project="$PROJECT_ID"

Requires service enablement permissions. Enable only services you need; subsequent usage can be billable.

Official reference

Storage

Read

List project buckets

List Cloud Storage buckets in the selected project.

TERMINAL / BASH
gcloud storage buckets list --project="$PROJECT_ID"

Requires bucket-list permissions; output can expose resource names.

Official reference

Storage

Read

List bucket objects

Inspect object paths in an existing bucket.

TERMINAL / BASH
gcloud storage ls "gs://$BUCKET_NAME/"

Storage request charges can apply, even to listing operations. Use consented documents only.

Official reference

Storage

Cloud change

Upload an invoice

Upload a local PDF to an existing bucket for a document-processing workflow.

TERMINAL / BASH
gcloud storage cp ./sample_invoice.pdf "gs://$BUCKET_NAME/document-ai/input/sample_invoice.pdf"

Creates or overwrites the target object and can incur charges. Confirm bucket access and data location first.

Official reference

Storage

Billable work

Download document results

Copy existing batch-processing output to a local directory.

TERMINAL / BASH
gcloud storage cp --recursive "gs://$BUCKET_NAME/document-ai/output/" ./document-ai-results/

Requires an already completed batch operation. Downloads can incur transfer charges and contain private text.

Official reference

Storage

Read

Preview directory synchronization

Preview copying a local directory to Cloud Storage without making changes.

TERMINAL / BASH
gcloud storage rsync ./documents "gs://$BUCKET_NAME/document-ai/input/" --recursive --dry-run

Removing --dry-run performs writes and can overwrite objects. This preview does not delete unmatched objects.

Official reference

AI & documents

Cloud change

Enable Document AI

Enable the Document AI API before creating a processor in the Google Cloud console.

TERMINAL / BASH
gcloud services enable documentai.googleapis.com --project="$PROJECT_ID"

Create the processor separately, then record its ID and supported location. Enabling the API alone does not process documents.

Official reference

AI & documents

Local setup

Install Document AI Python client

Prepare an isolated Python environment for the uploaded online-processing example.

TERMINAL / BASH
python -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-documentai

Bash/macOS/Linux activation shown. Windows PowerShell uses .venv\Scripts\Activate.ps1. Configure ADC separately.

Official reference

AI & documents

Local setup

Install Cloud Vision Python client

Install the client used by the image-labeling example into your active environment.

TERMINAL / BASH
python -m pip install google-cloud-vision

Installation does not make API calls. Running image annotation requires credentials, enabled API and billing.

Official reference

AI & documents

Read

List Vertex AI models

List registered models in a Vertex AI region.

TERMINAL / BASH
gcloud ai models list --project="$PROJECT_ID" --region="$REGION"

This is your regional model registry, not a list of every foundation model in Model Garden.

Official reference

AI & documents

Read

List Vertex AI endpoints

Inspect existing regional prediction endpoints.

TERMINAL / BASH
gcloud ai endpoints list --project="$PROJECT_ID" --region="$REGION"

Listing does not deploy a model or stop charges for an already deployed endpoint.

Official reference

BigQuery

Read

List BigQuery datasets

List datasets accessible within your project using the bq CLI.

TERMINAL / BASH
bq ls --project_id="$PROJECT_ID"

bq is a separate command bundled with the Google Cloud CLI; dataset visibility depends on IAM.

Official reference

BigQuery

Read

Validate a SQL query

Validate GoogleSQL without running a query job.

TERMINAL / BASH
bq query --project_id="$PROJECT_ID" --use_legacy_sql=false --dry_run 'SELECT 1 AS ready'

This literal query is a connectivity-free syntax example. For table queries, dry runs estimate bytes; they do not guarantee the final billed cost.

Official reference

BigQuery

Billable work

Run a minimal GoogleSQL query

Submit a minimal query job and display its result.

TERMINAL / BASH
bq query --project_id="$PROJECT_ID" --use_legacy_sql=false 'SELECT 1 AS ready'

Requires bigquery.jobs.create. This query scans no tables; replacing it with data queries can incur charges.

Official reference

Operations

Read

Read recent error logs

Inspect up to 20 error-level entries from the last hour.

TERMINAL / BASH
gcloud logging read 'severity>=ERROR' --project="$PROJECT_ID" --limit=20 --freshness=1h --format=json

Logs can contain personal data, document text or secrets. Redact before sharing; an empty result is not proof of health.

Official reference

Operations

Read

List Cloud Run services

Inspect existing Cloud Run services in a region.

TERMINAL / BASH
gcloud run services list --project="$PROJECT_ID" --region="$REGION" --platform=managed

Does not deploy or invoke a service. Existing running resources may remain billable.

Official reference

Operations

Read

Open command-specific help

Inspect supported flags and examples for your installed CLI version.

TERMINAL / BASH
gcloud storage cp --help

Use --help on any command before changing unfamiliar resources.

Official reference

Setup & auth

Local setup

Install beta CLI components

Install preview commands where your CLI installation supports the component manager.

TERMINAL / BASH
gcloud components install beta

Package-manager installations may require OS packages instead. Installing beta does not add an undocumented Document AI or pipelines command group.

Official reference

Projects & APIs

Cloud change

Enable Vertex AI

Enable the API used for custom training, pipelines and model serving.

TERMINAL / BASH
gcloud services enable aiplatform.googleapis.com --project="$PROJECT_ID"

Requires service enablement permissions; does not create a job or endpoint. Training and serving usage can incur charges.

Official reference

Custom training

Billable work

Launch a custom training job

Submit containerized training using worker pools defined in a local CustomJobSpec YAML file.

TERMINAL / BASH
read -r -p "Training job display name: " JOB_NAME
read -r -p "Existing CustomJobSpec YAML path: " CONFIG_YAML
gcloud ai custom-jobs create --display-name="$JOB_NAME" --config="$CONFIG_YAML" --project="$PROJECT_ID" --region="$REGION"

Review machine types, replica counts, images, identity and budget before submitting. The configuration must exist; compute and storage are billable. This is a managed job, not free serverless compute.

Official reference

Custom training

Read

List custom training jobs

Inspect up to 20 custom jobs in a region, including jobs in terminal states.

TERMINAL / BASH
gcloud ai custom-jobs list --project="$PROJECT_ID" --region="$REGION" --limit=20

Regional listing is not a global inventory or a full cost report. Requires access to the selected project.

Official reference

Custom training

Read

Inspect a custom training job

Read job state, configuration and available error details for an existing job.

TERMINAL / BASH
read -r -p "Existing custom job ID: " JOB_ID
gcloud ai custom-jobs describe "$JOB_ID" --project="$PROJECT_ID" --region="$REGION"

Description output is not a comprehensive compute metrics report; use monitoring and logs for execution diagnostics.

Official reference

Custom training

Read

Stream custom training logs

Follow available logs from the training workers.

TERMINAL / BASH
read -r -p "Existing custom job ID: " JOB_ID
gcloud ai custom-jobs stream-logs "$JOB_ID" --project="$PROJECT_ID" --region="$REGION"

Ctrl+C stops local streaming, not the training job. Logs may expose sensitive data; never log credentials or private training records.

Official reference

Custom training

Cloud change

Request training cancellation

Request cancellation of a running custom training job.

TERMINAL / BASH
read -r -p "Custom job ID to cancel: " JOB_ID
gcloud ai custom-jobs cancel "$JOB_ID" --project="$PROJECT_ID" --region="$REGION"

Check the exact job first. Cancellation is asynchronous, not instant; inspect state until cancellation completes. Work already performed remains billable, and stored artifacts are not automatically removed.

Official reference

Pipelines

Local setup

Install Vertex AI Python SDK

Install the SDK used by the pipeline submission and inspection examples in your active Python environment.

TERMINAL / BASH
python -m pip install google-cloud-aiplatform

Configure ADC separately. Install into an isolated environment; SDK installation does not compile or execute a pipeline.

Official reference

Pipelines

Billable work

Submit a compiled pipeline

Submit an already compiled pipeline with the Vertex AI SDK, not the unsupported gcloud ai pipelines runs syntax.

TERMINAL / BASH
read -r -p "Pipeline display name: " PIPELINE_NAME
read -r -p "Existing compiled pipeline JSON/YAML path: " PIPELINE_SPEC
read -r -p "Pipeline service account email: " PIPELINE_SERVICE_ACCOUNT
export PIPELINE_NAME PIPELINE_SPEC PIPELINE_SERVICE_ACCOUNT
python - <<'PY'
import os
from google.cloud import aiplatform
aiplatform.init(project=os.environ["PROJECT_ID"], location=os.environ["REGION"])
job = aiplatform.PipelineJob(
    display_name=os.environ["PIPELINE_NAME"],
    template_path=os.environ["PIPELINE_SPEC"],
    pipeline_root=f"gs://{os.environ['BUCKET_NAME']}/pipeline-root",
    enable_caching=False,
)
job.submit(service_account=os.environ["PIPELINE_SERVICE_ACCOUNT"])
print(job.resource_name)
PY

Use a spec with no unsupplied required parameters; otherwise add parameter_values. Review every component, identity permission and bucket location. Submission can launch billable training or other work; the caller needs permission to act as the specified service account.

Official reference

Pipelines

Read

Inspect recent pipeline runs

Display up to 20 recent regional pipeline jobs through the Python SDK.

TERMINAL / BASH
python - <<'PY'
import os
from itertools import islice
from google.cloud import aiplatform
aiplatform.init(project=os.environ["PROJECT_ID"], location=os.environ["REGION"])
for job in islice(aiplatform.PipelineJob.list(order_by="create_time desc"), 20):
    print(job.resource_name, job.state.name)
PY

The SDK list method may retrieve more results before local slicing; avoid this convenience snippet for large inventories. Results are regional, not global; inspect full details in the console or SDK.

Official reference

Model serving

Cloud change

Create a prediction endpoint

Create an endpoint resource before deploying a compatible registered model.

TERMINAL / BASH
read -r -p "Endpoint display name: " ENDPOINT_NAME
gcloud ai endpoints create --display-name="$ENDPOINT_NAME" --project="$PROJECT_ID" --region="$REGION"

This command does not deploy a model or set up private networking. A standard endpoint requires authorized prediction calls. Review networking requirements before creation.

Official reference

Model serving

Billable work

Deploy a registered model

Deploy a compatible model with one serving replica and route all endpoint traffic to the new deployment.

TERMINAL / BASH
read -r -p "Existing endpoint ID: " ENDPOINT_ID
read -r -p "Compatible registered model ID: " MODEL_ID
read -r -p "Deployment display name: " DEPLOYED_NAME
gcloud ai endpoints deploy-model "$ENDPOINT_ID" --model="$MODEL_ID" --display-name="$DEPLOYED_NAME" --machine-type=n1-standard-4 --min-replica-count=1 --max-replica-count=1 --traffic-split=0=100 --project="$PROJECT_ID" --region="$REGION"

Changes existing traffic. The example machine must suit your model; registry membership does not certify quality or compatibility. Provisioned replicas can remain billable without requests. Undeploy separately when no longer needed.

Official reference

Model serving

Billable work

Send an online prediction request

Send a JSON prediction request to a supported endpoint with a deployed model.

TERMINAL / BASH
read -r -p "Existing deployed endpoint ID: " ENDPOINT_ID
read -r -p "Model-compatible JSON request path: " PAYLOAD_FILE
gcloud ai endpoints predict "$ENDPOINT_ID" --json-request="$PAYLOAD_FILE" --project="$PROJECT_ID" --region="$REGION"

Use the model’s required instances/parameters schema and consented inputs. Calls can incur charges and send data to the endpoint; output is not guaranteed accurate. Dedicated or private endpoints may require another prediction interface.

Official reference

AI & documents

Read

List Document AI processors

List up to 20 existing processors with the official Document AI Python client and matching location endpoint.

TERMINAL / BASH
read -r -p "Processor location (e.g. us or eu): " DOC_LOCATION
export DOC_LOCATION
python - <<'PY'
import os
from itertools import islice
from google.api_core.client_options import ClientOptions
from google.cloud import documentai
location = os.environ["DOC_LOCATION"]
client = documentai.DocumentProcessorServiceClient(
    client_options=ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")
)
parent = f"projects/{os.environ['PROJECT_ID']}/locations/{location}"
processors = client.list_processors(request={"parent": parent, "page_size": 20})
for processor in islice(processors, 20):
    print(processor.name, processor.display_name, processor.type_, processor.state.name)
PY

Install google-cloud-documentai and configure ADC first. Use a supported processor location, not the Vertex AI region. Processor creation is documented in the console/API; gcloud beta document-ai processors is not an official command group.

Official reference

Agent development

Local setup

Set up Google agents-cli

Initialize Google agents-cli and its coding-agent skill definitions.

TERMINAL / BASH
uvx google-agents-cli setup

Install uv first. This downloads and runs third-party tooling locally; review the source and installation changes. It does not create a Cloud agent or grant Cloud permissions.

Official reference

Agent development

Local setup

Create a local agent prototype

Scaffold a local prototype; the project name is positional, not --name.

TERMINAL / BASH
read -r -p "New agent project directory: " AGENT_NAME
agents-cli create "$AGENT_NAME" --prototype

Choose a new directory. Prototype mode avoids deployment scaffolding; it does not sandbox arbitrary tools or guarantee the generated agent is production-ready.

Official reference

Agent development

Local setup

Install agent project dependencies

Install dependencies from an existing agents-cli project directory.

TERMINAL / BASH
agents-cli install

Run inside the generated project, after reviewing its dependency definitions. Installation executes local package tooling; do not install untrusted projects.

Official reference

Agent development

Billable work

Open the agent playground

Launch the local development playground for an existing configured agent project.

TERMINAL / BASH
agents-cli playground

Local web hosting is not a containerized security sandbox. Conversations can call real models and tools with your configured access and incur charges. Use draft-only tools and keep the server private.

Official reference

Agent development

Billable work

Evaluate an agents-cli project

Run the project’s evaluation datasets against its configured agent.

TERMINAL / BASH
agents-cli eval run

Requires prepared datasets and model authentication. Evaluation may call models and tools repeatedly; use synthetic data and safe tool stubs. Passing tests is not a safety or accuracy certification.

Official reference

Agent hosting

Read

Preview an agent deployment

Preview the deployment pipeline from a deployment-ready agents-cli project.

TERMINAL / BASH
agents-cli deploy --dry-run

Review the configured deployment target, project, region and infrastructure plan. A prototype must first gain deployment scaffolding. Previewing is not a cost estimate or permission guarantee.

Official reference

Agent hosting

Billable work

Deploy an agents-cli project

Deploy the project to its configured Cloud hosting target.

TERMINAL / BASH
agents-cli deploy --project="$PROJECT_ID" --region="$REGION"

Review the dry run first. May create or update billable infrastructure and change serving behavior; the target is set by project configuration. Deployment and publishing to Gemini Enterprise are separate lifecycle steps, not automatic dashboard access.

Official reference

Agent development

Local setup

Install Google ADK

Install the official Python Agent Development Kit into an isolated environment.

TERMINAL / BASH
python -m venv .venv
source .venv/bin/activate
python -m pip install google-adk

Bash activation shown; Windows uses its corresponding activation script. Installation does not authenticate a model. Keep any provider credentials outside code and shared terminal history.

Official reference

Agent development

Local setup

Scaffold an ADK agent

Generate a Python ADK agent project through the interactive CLI.

TERMINAL / BASH
read -r -p "New ADK agent directory: " AGENT_DIR
adk create "$AGENT_DIR"

Use a new directory, review generated code and configure model access separately. Do not paste private API keys into command flags or publish generated credential files.

Official reference

Agent development

Billable work

Run an ADK agent in the terminal

Start a terminal conversation with an existing ADK agent.

TERMINAL / BASH
read -r -p "Existing ADK agent directory: " AGENT_DIR
adk run "$AGENT_DIR"

This executes agent code locally and may invoke real tools and billable model calls. Keep external actions approval-gated; Ctrl+C ends this local process, not previously submitted Cloud jobs.

Official reference

Agent development

Billable work

Serve the ADK development UI

Serve the ADK web interface from the parent directory containing your agent folders.

TERMINAL / BASH
adk web . --host=127.0.0.1 --port=8501

Development-only local server, not a container or production sandbox. Do not expose it to public networks. Agent interactions can call paid models and real tools. In a uv-managed project with google-adk installed, uv run adk web . --port 8501 is an alternative.

Official reference

Agent development

Billable work

Evaluate an ADK agent

Evaluate the configured agent against an existing ADK evaluation set.

TERMINAL / BASH
read -r -p "Existing agent module path: " AGENT_MODULE
read -r -p "Existing evaluation set JSON path: " EVAL_FILE
adk eval "$AGENT_MODULE" "$EVAL_FILE" --print_detailed_results

Evaluation sets must match the ADK format. Calls can be billable and tool actions real; isolate tools and use consented synthetic cases. Detailed output can contain sensitive conversation text.

Official reference

Agent hosting

Billable work

Deploy ADK to Agent Engine

Package and deploy an existing ADK agent to the managed Agent Engine runtime.

TERMINAL / BASH
read -r -p "Existing ADK agent directory: " AGENT_DIR
read -r -p "Agent display name: " AGENT_DISPLAY_NAME
adk deploy agent_engine --project="$PROJECT_ID" --region="$REGION" --display_name="$AGENT_DISPLAY_NAME" "$AGENT_DIR"

Creates a new instance unless an update ID is supplied. Requires supported region, enabled API, billing, compatible dependencies and deployment permissions. Review runtime identity and tool access; hosted execution can incur charges. Gemini Enterprise publication is separate.

Official reference

Agent hosting

Cloud change

Enable the agent hosting API

Enable the Vertex AI API used for Agent Engine resources.

TERMINAL / BASH
gcloud services enable aiplatform.googleapis.com --project="$PROJECT_ID"

Corrects the malformed ://googleapis.com service name in the upload. API activation alone does not provision a runtime, enable every deployment dependency or grant IAM roles.

Official reference

Agent hosting

Read

List hosted agent engines

Inspect regional hosted resources using Google’s documented preview Python SDK sample.

TERMINAL / BASH
python - <<'PY'
import os
from itertools import islice
import vertexai
from vertexai.preview import reasoning_engines
vertexai.init(project=os.environ["PROJECT_ID"], location=os.environ["REGION"])
for engine in islice(reasoning_engines.ReasoningEngine.list(), 20):
    print(engine.resource_name)
PY

Install google-cloud-aiplatform and configure ADC first. The SDK can retrieve more results before local slicing; use paginated API reads for large inventories. The uploaded gcloud alpha ai reasoning-engines group has no verified official command reference; use this SDK alternative.

Official reference

Agent hosting

Read

Inspect a hosted agent engine

Resolve an existing hosted agent resource with the documented preview SDK.

TERMINAL / BASH
read -r -p "Existing agent engine resource ID: " ENGINE_ID
export ENGINE_ID
python - <<'PY'
import os
import vertexai
from vertexai.preview import reasoning_engines
vertexai.init(project=os.environ["PROJECT_ID"], location=os.environ["REGION"])
engine = reasoning_engines.ReasoningEngine(os.environ["ENGINE_ID"])
print(engine.resource_name)
PY

Requires the matching project, region and read permissions. This prints resource identity, not a complete audit of tool access or runtime IAM. Preview SDK interfaces may change; inspect full configuration in the console before any deletion.

Official reference