Gemini CLI Usage Monitor

A Gemini CLI extension that monitors your Google Cloud API usage and compares it against subscription plan limits.

This extension provides a simple way to check your Google Cloud API usage directly from the Gemini CLI. It queries the Google Cloud Monitoring API to fetch your API request count and compares it against your subscription plan limits.

• 🔍 Query API usage for any Google Cloud project
• 📊 Compare usage against subscription plan limits (Free, Pro, Ultra, Standard, Enterprise)
• ⚡ Visual status indicators (OK, LOW, WARNING, OVER LIMIT)
• 📅 Automatic querying of the most recent complete UTC day
• 🔐 Secure authentication using Google Cloud Application Default Credentials

• Gemini CLI v0.8.2 or later
• Python 3.6 or later (included with most systems)
• A Google Cloud project with billing enabled
• Access to Google Cloud Monitoring API

No pip packages, gcloud CLI, or system modifications required! This extension uses only Python standard library and authenticates using your existing Gemini CLI credentials.

Install directly from the git repository - no additional dependencies or setup required:

gemini extensions install https://github.com/yourusername/geminicli-usage.git

That's it! The extension is ready to use.

Before using the extension, you need to:

If you haven't already, authenticate with Gemini CLI:

gemini

Follow the prompts to sign in with your Google account. This creates authentication credentials that the extension will use.

The extension requires the Cloud Monitoring API to be enabled in your Google Cloud project. Enable it via the Google Cloud Console:

1. Visit the Cloud Monitoring API page
2. Select your project
3. Click "Enable"

Note: Most Google Cloud APIs, including the Generative Language API, are not enabled by default and must be activated manually.

⚠️ Interactive mode only - The extension works in interactive chat. The -p (prompt) flag currently has a known bug, likely related to Gemini CLI's MCP implementation, which causes the command to hang indefinitely.

Start Gemini CLI:

gemini

Then ask about your usage in natural language:

> Check my usage for project my-project-123 on the pro plan

The extension provides a check_usage tool that Gemini will automatically invoke.

> Check my usage for project my-project-123 on the pro plan

> What's my API usage for project my-gcp-project on the free plan?

> Show usage for project my-project, I'm on the ultra plan

> How many API requests have I used today for project my-company-project on the enterprise plan?

Gemini API Usage Report - 2025-10-17

Total Requests: 1,367

Plan: Google AI Pro
  Limit:     1,500 requests/day
  Used:      1,367 requests
  Remaining: 133 requests (8.9% available)
  Status:    ⚠️  WARNING

💡 Consider upgrading your plan if you frequently approach this limit.

Tip: Be specific in your prompts. Include both the project ID and plan type clearly.

• free: 1,000 requests/day
• pro: 1,500 requests/day (Google AI Pro)
• ultra: 2,000 requests/day (Google AI Ultra)
• standard: 1,500 requests/day
• enterprise: 2,000 requests/day

The extension displays one of four status indicators based on your usage:

• ✓ OK: Usage is below 75% of your daily limit (comfortable usage level)
• ⚡ LOW: Usage is between 75% and 90% of your daily limit (approaching limit)
• ⚠️ WARNING: Usage is between 90% and 100% of your daily limit (very close to limit)
• ❌ OVER LIMIT: Usage has exceeded 100% of your daily limit (rate limiting may occur)

The extension queries the last 7 days of data by default to ensure metrics are available. The report shows usage for the most recent complete day.

Problem: Command hangs indefinitely with no response

Solution: Use interactive mode only. The -p (prompt) flag has a known bug, likely related to Gemini CLI's MCP implementation:

# ❌ Does not work - hangs indefinitely
gemini -p 'check my usage...'

# ✅ Works
gemini
> check my usage for project X on plan Y

This appears to be a bug in Gemini CLI's handling of MCP tool calls when using the -p flag, not a limitation of this extension.

Problem: "Permission denied accessing project" or "Failed to get access token"

Solutions:

1. Ensure you've authenticated with Gemini CLI first by running gemini and following the sign-in prompts (this creates ~/.gemini/oauth_creds.json)
2. Verify your project ID is correct
3. Check you have the required IAM role via the Google Cloud Console IAM page:
   • You need at least the Monitoring Viewer role (roles/monitoring.viewer)
   • Or any role that includes the monitoring.timeSeries.list permission

Problem: "Cloud Monitoring API may not be enabled"

Solution: Enable the API via the Google Cloud Console:

1. Visit the Cloud Monitoring API page
2. Select your project
3. Click "Enable"

The API is not enabled by default and must be activated manually for each project.

Problem: Query returns 0 requests but you know you've made API calls

Possible causes:

1. The metric may not be available yet (monitoring data has a delay)
2. You're querying the wrong project ID
3. The API calls were made to a different service

Solution:

• Wait a few minutes for metrics to populate (monitoring data has inherent delays)
• Verify your project ID is correct
• Check the Google Cloud Console Monitoring page to see available metrics for your project

To remove the extension:

gemini extensions uninstall gemini-usage-monitor

Contributions are welcome! Please feel free to submit issues or pull requests.

Apache 2.0 - See LICENSE file for details

For issues or questions:

• Check the troubleshooting section above
• Review the Gemini CLI Extensions Documentation
• File an issue in the repository