Gcloud Skill

Google Cloud Skill

Wrapper over the official Google Cloud CLI (gcloud). Typed operations for the core flows plus a custom passthrough that covers the entire gcloud surface. JSON-capable operations run with --format=json, so results come back parsed in result.

Each call starts a fresh gcloud process — a few seconds of startup latency per call is normal; don't retry a slow call.

Tool: gcloud

Operations

The project / zone / region fields map to --project / --zone / --region. When project is empty, gcloud falls back to the configured default — run set_project once instead of repeating project on every call.

Response

jsonCopy code
{
  "operation": "projects_list",
  "success": true,
  "result": [{ "projectId": "my-project-123", "name": "My Project", "lifecycleState": "ACTIVE" }]
}

Parsed JSON lands in result; plain text (set_project, storage_cp progress) lands in stdout. On failure the tool raises an error carrying gcloud's own message — surface it verbatim; gcloud's errors are precise (including "You do not currently have an active account selected", which means the user needs to log in via Credentials -> Google Cloud).

Typical flows

Orient first when state is unknown:

jsonCopy code
{ "operation": "auth_list" }
{ "operation": "config_list" }
{ "operation": "projects_list" }
{ "operation": "set_project", "project_id": "my-project-123" }

Compute Engine — zone is required for single-instance operations (get it from the list output's zone field):

jsonCopy code
{ "operation": "compute_instances_list" }
{ "operation": "compute_instance_stop", "instance": "my-vm", "zone": "us-central1-a" }

Cloud Run — deploy from a container image, or from source (source deploys run Cloud Build and can take minutes; the 15-minute timeout accommodates that):

jsonCopy code
{ "operation": "run_deploy", "service": "my-api", "region": "us-central1", "image": "gcr.io/my-project/my-api:latest", "allow_unauthenticated": true }
{ "operation": "run_deploy", "service": "my-api", "region": "us-central1", "source": ".", "path": "app" }
{ "operation": "run_service_describe", "service": "my-api", "region": "us-central1" }

The deployed URL is in the describe/deploy result under status.url.

Cloud Storage — local paths resolve against the workflow workspace:

jsonCopy code
{ "operation": "storage_ls", "url": "gs://my-bucket/reports/" }
{ "operation": "storage_cp", "src": "gs://my-bucket/reports/latest.csv", "dst": "./downloads/" }
{ "operation": "storage_cp", "src": "./build", "dst": "gs://my-bucket/site/", "recursive": true }

The full gcloud surface via custom

jsonCopy code
{ "operation": "custom", "command": "iam service-accounts list" }
{ "operation": "custom", "command": "sql instances list" }
{ "operation": "custom", "command": "functions deploy my-fn --runtime python312 --trigger-http --region us-central1" }
{ "operation": "custom", "command": "container clusters list" }
{ "operation": "custom", "command": "logging read \"severity>=ERROR\" --limit 20 --format=json" }
{ "operation": "custom", "command": "services enable run.googleapis.com" }

Notes for custom:

• Add --format=json yourself when you want parsed output — it is not injected for you.
• command is parsed with shlex.split — wrap filter expressions and JSON in quotes as you would in a shell.
• Long-running commands get a 10-minute timeout; for very long operations prefer the --async flag and poll.
• auth application-default login mints Application Default Credentials for client-library code (stored isolated under OpenCompany's data directory). gcloud CLI commands themselves never need ADC.

Authentication

Auth is owned by the gcloud CLI itself, isolated under OpenCompany's data directory (a login you did in your own terminal is NOT visible here):

• Credentials Modal -> Google Cloud -> Login — gcloud opens the browser itself for Google sign-in (localhost callback, so the browser must be on the server's machine). First use auto-installs the CLI (~100 MB; allow a few minutes).

If a command fails with an auth error, point the user at the Login button; don't ask them to paste credentials in chat. If it fails with "API not enabled", enable it via { "operation": "custom", "command": "services enable <api>.googleapis.com" }.

Best practices

1. Run config_list first when state is unknown — it shows the active account and default project without side effects.
2. Set the project once (set_project) instead of repeating the project field.
3. Destructive operations (instance stop, storage_rm, deletes via custom) — confirm with the user before running unless they explicitly asked.
4. Surface gcloud error messages verbatim — don't paraphrase; they name the exact flag, permission, or API to fix.
5. Costs are real — starting instances and deploying services incurs billing; mention it when the user's intent is exploratory.