{
  "markdown": "# Vertex AI Billing Switch for Gemini CLI\n\n[![Version](https://img.shields.io/badge/version-1.4.1-blue.svg)](./skills/en/SKILL.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()\n\n[繁體中文版](./README.zh-TW.md)\n\nA **Gemini CLI Skill** that automates GCP Vertex AI authentication setup and deploys a global billing auto-switch Hook — helping newcomers get Vertex AI running with zero manual configuration.\n\n---\n\n> [!WARNING]\n> **IMPORTANT DISCLAIMER**\n>\n> This tool is designed **only** for Google Cloud accounts **without any credit card or payment method attached**.\n>\n> If a payment method is attached to your account, unexpected charges may occur. **The authors are not responsible for any charges incurred.** Please verify your account has no payment method before proceeding.\n\n---\n\n## Features\n\n- **Interactive setup wizard** — 7-step guided process, no manual configuration needed\n- **Auto-create GCP project** — create a new GCP project via `gcloud` CLI without leaving the terminal\n- **Quick switch mode** — returning users can switch GCP projects without re-authentication; switching Google accounts still opens a browser\n- **Billing account renaming** — rename billing accounts to include expiration dates for easier identification (e.g., `Trial_Exp_20260501`)\n- **Automatic gcloud installation** — detects and installs Google Cloud CLI if missing (Windows / macOS / Linux)\n- **ADC authentication** — configures Application Default Credentials for Vertex AI\n- **Billing auto-switch Hook** — deployed as a Gemini CLI `SessionStart` hook, runs automatically on every startup\n- **Smart account switching** — scans available billing accounts and switches when quota is exhausted\n- **Cross-platform** — supports Windows, macOS, and Linux\n- **Non-destructive** — never overwrites existing `settings.json` keys; only adds what's needed\n- **Bilingual** — available in English and Traditional Chinese\n\n---\n\n## Prerequisites\n\n- [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed\n- [Node.js](https://nodejs.org/) (for the Hook script at runtime)\n- A Google Cloud account (**no credit cards attached to billing accounts**)\n  - If you already have a GCP project: the skill will use it directly\n  - If not: the skill can auto-create one for you (requires at least one billing account with credits)\n  - Each billing account needs an active billing plan set up in Google AI Studio\n\n---\n\n## Quick Start\n\n### Run in your standard terminal / command prompt:\n\n1. **Install the Skill:**\n\n   ```bash\n   gemini extensions install https://github.com/AndyAWD/VertexAiBillingSwitchSkill\n   ```\n\n2. **Update the Skill:**\n\n   ```bash\n   gemini extensions update vertex-ai-billing-switch-skill\n   ```\n\n### Run in Gemini CLI:\n\n1. **Run the Skill:**\n\n   ```\n   /vertex-ai-billing-switch-skill:en run the skill workflow\n   ```\n\n2. After setup completes:\n   - Type `/quit` to exit Gemini CLI\n   - **Restart Gemini CLI**, then type `/auth` to switch to **Vertex AI** authentication mode\n   - Type `/model` to choose your preferred model\n\n---\n\n## How It Works\n\n### Setup Wizard\n\n```\n/en run the skill workflow\n        │\n        ▼\n  Step 0 ── Disclaimer confirmation\n        │\n        ▼\n  Step 1 ── Environment detection\n             ├─ All ready (returning user) → Switch project, Rename accounts, or Full reset\n             │   ├─ Switch project → Same account: skip to Step 4\n             │   │                 → Switch account: Step 3 → Step 4\n             │   └─ Rename accounts → Step R → Done\n             └─ Not ready (first-time) → Continue full flow ↓\n        │\n        ▼\n  Step 2 ── Check / auto-install gcloud CLI\n        │\n        ▼\n  Step 3 ── GCP auth login\n        │\n        ▼\n  Step 4 ── Get / Create GCP project\n             ├─ Enter existing project ID\n             └─ Auto-create via gcloud (detect billing → name → create → link)\n        │\n        ▼\n  Step 5 ── GCP config + Gemini CLI deployment\n             ├─ gcloud config set project\n             ├─ Enable Vertex AI API\n             ├─ gcloud auth application-default login (ADC)\n             ├─ ~/.gemini/.env  (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION)\n             ├─ ~/.gemini/settings.json  (register Hook)  [first-time only]\n             └─ ~/.gemini/hooks/vertex-ai-billing-switch-hook.mjs  [first-time only]\n        │\n        ▼\n  Step 6 ── Verify all items → Done\n```\n\n### Billing Auto-Switch Hook (every Gemini CLI startup)\n\n```\nGemini CLI starts → SessionStart Hook fires\n        │\n        ▼\n  Check current billing account status\n        │\n        ├─ OK ──────────────────────────────► Continue normally\n        │\n        └─ Quota exhausted / Account closed\n                │\n                ▼\n          Scan all available billing accounts\n                │\n                ▼\n          Switch to an available account\n                │\n                ▼\n          Verify link success → Continue\n```\n\n---\n\n## What Gets Deployed\n\n| File | Location | Purpose |\n|------|----------|---------|\n| `.env` | `~/.gemini/.env` | Sets `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` |\n| `settings.json` | `~/.gemini/settings.json` | Registers the `SessionStart` hook |\n| Hook script | `~/.gemini/hooks/vertex-ai-billing-switch-hook.mjs` | Billing auto-switch logic |\n\n---\n\n## Repository Structure\n\n```\nVertexAiBillingSwitchSkill/\n├── README.md                              # This file (English)\n├── README.zh-TW.md                        # Traditional Chinese version\n├── package.json                           # NPM package manifest\n├── gemini-extension.json                  # Gemini CLI extension manifest\n│\n└── skills/                                # Gemini CLI Skills directory\n    ├── en/       # English Skill\n    │   ├── SKILL.md                       # Skill definition (loaded by Gemini CLI)\n    │   ├── references/                    # On-demand reference docs\n    │   │   ├── config-and-verify.md       # Config and Verification (Step 5 & 6)\n    │   │   ├── install-gcloud.md          # Platform-specific gcloud installation\n    │   │   ├── create-project.md          # Auto-create GCP project sub-flow\n    │   │   ├── deploy-hook.md             # First-time Hook deployment\n    │   │   └── rename-accounts.md         # Batch rename billing accounts\n    │   ├── assets/\n    │   │   └── vertex-ai-billing-switch-hook.mjs\n    │   └── scripts/\n    │       ├── install-gcloud.mjs\n    │       └── consume-credits.mjs\n    │\n    └── zh-tw/    # Traditional Chinese Skill\n        ├── SKILL.md                       # Skill 定義（由 Gemini CLI 載入）\n        ├── references/                    # 按需讀取的參考文件\n        │   ├── config-and-verify.md\n        │   ├── install-gcloud.md\n        │   ├── create-project.md\n        │   ├── deploy-hook.md\n        │   └── rename-accounts.md\n        ├── assets/\n        │   └── vertex-ai-billing-switch-hook.mjs\n        └── scripts/\n            ├── install-gcloud.mjs\n            └── consume-credits.mjs\n```\n\n---\n\n## Contributing a New Language\n\nWant to add your language? You only need to translate a few Markdown files — the code files can be copied as-is. No engineering skills required.\n\n### What to do with each file\n\n| File | Action |\n|------|--------|\n| `skills/en/SKILL.md` | Translate + update paths |\n| `skills/en/references/config-and-verify.md` | Translate + update paths |\n| `skills/en/references/deploy-hook.md` | Translate + update paths |\n| `skills/en/references/create-project.md` | Translate |\n| `skills/en/references/install-gcloud.md` | Translate |\n| `skills/en/references/rename-accounts.md` | Translate |\n| `skills/en/assets/vertex-ai-billing-switch-hook.mjs` | Copy as-is — no changes needed |\n| `skills/en/scripts/install-gcloud.mjs` | Copy as-is — no changes needed |\n| `skills/en/scripts/consume-credits.mjs` | Copy as-is — no changes needed |\n\n### Use AI to do it in one shot\n\nCopy the prompt below to your AI. Replace `[LANG_CODE]` with your language code (e.g. `ja`) and `[TARGET_LANGUAGE]` with the language name (e.g. `Japanese`):\n\n````\nI want to add a [TARGET_LANGUAGE] translation of this Gemini CLI skill (language code: [LANG_CODE]).\n\n## Files to translate\nTranslate the Markdown body (everything after the `---` frontmatter block) from English to [TARGET_LANGUAGE] for these files:\n- `skills/en/SKILL.md`\n- `skills/en/references/config-and-verify.md`\n- `skills/en/references/deploy-hook.md`\n- `skills/en/references/create-project.md`\n- `skills/en/references/install-gcloud.md`\n- `skills/en/references/rename-accounts.md`\n\n## Rules — MUST follow\n- Keep ALL code blocks (``` blocks) unchanged — do NOT translate code\n- Keep ALL JSON objects unchanged — do NOT translate keys or values\n- Keep ALL variable placeholders like `{home_dir}`, `{project_id}`, `{skill_dir}` unchanged\n- Keep ALL markdown headings (##), tables, and formatting unchanged\n- Only translate human-readable prose and UI strings (questions, labels, descriptions, and informational messages)\n\n## After translating — apply these exact string replacements\n\nIn `SKILL.md` frontmatter, replace:\n- `name: en` → `name: [LANG_CODE]`\n\nIn `SKILL.md` body, replace these 3 exact strings:\n1. `{home_dir}/.gemini/skills/en` → `{home_dir}/.gemini/skills/[LANG_CODE]`\n2. `/en run the skill workflow` → `/[LANG_CODE] [TRANSLATED_COMMAND]`\n3. `` run `/en run the skill workflow` `` → `` run `/[LANG_CODE] [TRANSLATED_COMMAND]` ``\n\nIn `references/config-and-verify.md`, replace this exact string:\n1. `/.gemini/skills/en` → `/.gemini/skills/[LANG_CODE]`\n\nIn `references/deploy-hook.md`, replace these 2 exact strings:\n1. `extensions/VertexAiBillingSwitchSkill/skills/en` → `extensions/VertexAiBillingSwitchSkill/skills/[LANG_CODE]`\n2. `/.gemini/skills/en` → `/.gemini/skills/[LANG_CODE]`\n\n## Files to copy WITHOUT modification\nCopy these files exactly as-is (do not translate):\n- `skills/en/assets/vertex-ai-billing-switch-hook.mjs`\n- `skills/en/scripts/install-gcloud.mjs`\n- `skills/en/scripts/consume-credits.mjs`\n\n## Output structure\nSave everything under `skills/[LANG_CODE]/` with this exact structure:\n```\nskills/[LANG_CODE]/\n├── SKILL.md\n├── references/\n│   ├── config-and-verify.md\n│   ├── deploy-hook.md\n│   ├── create-project.md\n│   ├── install-gcloud.md\n│   └── rename-accounts.md\n├── assets/\n│   └── vertex-ai-billing-switch-hook.mjs\n└── scripts/\n    ├── install-gcloud.mjs\n    └── consume-credits.mjs\n```\n\n## Self-check before finishing\n- [ ] `SKILL.md` frontmatter has `name: [LANG_CODE]`\n- [ ] No occurrence of `skills/en` remains in any translated file\n- [ ] No occurrence of `/en ` (as a skill command) remains in SKILL.md\n- [ ] All `.mjs` files are identical to the originals in `skills/en/`\n````\n\nOnce done, open a Pull Request with the `skills/[LANG_CODE]/` directory!\n\n---\n\n## Testing the Hook\n\nA `consume-credits.mjs` script is included to intentionally exhaust quota and verify the auto-switch mechanism works:\n\n```bash\nnode skills/en/scripts/consume-credits.mjs\n```\n\nThe script sends large Vertex AI API requests in a loop until a `402`, `BILLING_DISABLED`, or quota-exceeded error is returned, which triggers the Hook on next Gemini CLI startup.\n\n---\n\n## License\n\nMIT © 2024\n\nSee [LICENSE](./LICENSE) for details.\n\n",
  "bytes": 11263,
  "sha": "23e8a85b15819876c57dce174712539ad4bbf45b8b83392a8208b8ccc571a430",
  "repo_slug": "andyawd/vertexaibillingswitchskill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_andyawd_vertexaibillingswitchskill_fa2a82d1/readme"
}