alexei-led/using-cloud-cli

<!-- generated by scripts/build/generate-skills.py — edits to this file will be overwritten by `make build`. Edit the canonical SKILL.md (or add a SKILL.codex.md / SKILL.pi.md sidecar to diverge). --> <!-- Platform guidance for non-Claude models (Codex CLI, Gemini CLI) --> <!-- Persistence: Keep going until the task is fully resolved. Do not stop at the first obstacle. --> <!-- Tool use: Use available tools to verify — do not guess at file contents, paths, or command output. --> <!-- Planning: Reflect between steps. Decompose complex problems into logical sub-steps before acting. --> <!-- Reliability: Assess risk before irreversible actions. Ask for clarification on ambiguity. --> <!-- Completeness: Generate complete responses without truncating. Review your output against the original constraints. -->

Cloud CLI Patterns

Credentials may be pre-configured. Verify identity before touching resources. Use --help or Context7 for syntax.

Safety and Identity

Before destructive commands (delete, destroy, rm, terminate, IAM changes, bucket/object deletion):

Do not present executable delete commands as the next action until identity and candidate resources have been shown and the user has explicitly confirmed the exact resources. A safe answer may show inventory/dry-run commands first, then say deletion commands come only after confirmation.

1. Confirm the active cloud target:
   • AWS: aws sts get-caller-identity plus explicit --profile and --region when relevant.
   • GCP: gcloud config get-value account and gcloud config get-value project, or pass explicit --project.
2. Inventory candidate resources with non-destructive list/describe commands.
3. Present the exact command, account/profile, project, region/zone, and resources affected.
4. Require explicit user confirmation before execution. Do not rely on --quiet, default profiles, or implicit projects for destructive work.

BigQuery

# Always estimate cost first
bq query --dry_run --use_legacy_sql=false 'SELECT ...'

# Run query
bq query --use_legacy_sql=false --format=json 'SELECT ...'

# List tables
bq ls project:dataset

# Get table schema
bq show --schema --format=json project:dataset.table

Cost awareness: Charged per bytes scanned. Use --dry_run, partition tables, specify columns.

GCP (gcloud)

# List resources
gcloud compute instances list --format=json

# Describe resource
gcloud compute instances describe INSTANCE --zone=ZONE --format=json

# Create with explicit project
gcloud compute instances create NAME --project=PROJECT --zone=ZONE

# Destructive: confirm active account/project first, then ask the user
gcloud config get-value account
gcloud config get-value project
gcloud compute instances delete NAME --project=PROJECT --zone=ZONE

AWS

# List resources
aws ec2 describe-instances --output json

# With JMESPath filtering
aws ec2 describe-instances --query 'Reservations[].Instances[].InstanceId' --output text

# Explicit region
aws s3 ls s3://bucket --region us-west-2

# Dry run where available
aws ec2 run-instances --dry-run ...

Error Handling & Recovery

Authentication Failures

GCP auth issues:

# Check current auth status
gcloud auth list

# Re-authenticate user
gcloud auth login

# Re-authenticate application default credentials
gcloud auth application-default login

# For service accounts
gcloud auth activate-service-account --key-file=key.json

AWS auth issues:

# Check current identity
aws sts get-caller-identity

# Verify credentials file
cat ~/.aws/credentials

# Use specific profile
aws s3 ls --profile production

# Refresh SSO credentials
aws sso login --profile my-sso-profile

Common auth errors:

| Error | Cause | Fix | | ---------------------- | ----------------- | ----------------------- | | UNAUTHENTICATED | No credentials | Run gcloud auth login | | AccessDenied | Wrong permissions | Check IAM roles | | ExpiredToken | Session expired | Re-authenticate | | InvalidClientTokenId | Bad AWS key | Verify credentials file |

Rate Limiting

Symptoms:

• 429 Too Many Requests
• RESOURCE_EXHAUSTED
• Throttling errors

Mitigation:

# Add delays between operations
for bucket in $(aws s3 ls | awk '{print $3}'); do
  aws s3 ls "s3://$bucket" --summarize
  sleep 1  # Prevent throttling
done

# Use pagination instead of large requests
aws ec2 describe-instances --max-items 100 --starting-token "$TOKEN"

# For BigQuery: Use batch queries, avoid rapid-fire
bq query --batch 'SELECT ...'  # Lower priority, less throttling

API quotas:

• Check quotas: gcloud compute project-info describe --project=PROJECT
• Request increase: Console → IAM → Quotas

Common Error Patterns

Resource not found:

# Verify resource exists first
gcloud compute instances describe NAME --zone=ZONE 2>/dev/null || echo "Not found"

# List available resources
gcloud compute zones list --filter="region:us-central1"

Permission denied:

# Check your roles
gcloud projects get-iam-policy PROJECT --flatten="bindings[].members" \
  --filter="bindings.members:$(gcloud config get-value account)"

# For AWS
aws iam get-user
aws iam list-attached-user-policies --user-name USERNAME

Region/zone mismatch:

# Always specify explicitly
gcloud compute instances create NAME --zone=us-central1-a  # Not just region!
aws ec2 run-instances --region us-west-2 ...

Retry Patterns

# Simple retry with backoff
retry_cmd() {
  local max_attempts=3
  local delay=2
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    if "$@"; then return 0; fi
    echo "Attempt $attempt failed, retrying in ${delay}s..."
    sleep $delay
    delay=$((delay * 2))
    attempt=$((attempt + 1))
  done
  return 1
}

retry_cmd gcloud compute instances start my-instance --zone=us-central1-a

References

• GCP.md - GCP service patterns and common commands
• AWS.md - AWS service patterns and common commands
• scripts/ - Helper scripts for common operations