Gemini CLI · macOS how-to

How to check Gemini CLI usage limits on a Mac.

Q: How do I check my Gemini CLI usage in the terminal?

Inside an interactive gemini session, run /stats for session token and request totals or /stats model for per-model breakdown.

Facts first: Since June 18, 2026, Google’s Gemini CLI (gemini) is for Gemini Code Assist Standard and Enterprise, Code Assist for GitHub, and paid Gemini API or Vertex AI keys. Free personal Google accounts and Google AI Pro and Ultra moved to Google’s Antigravity CLI (agy), and their quota now shows there, in its /quota panel (Gemini CLI README). Inside a Gemini CLI session, /stats shows that session’s usage and /stats model shows token counts and quota information.

If you want your Google quota in the Mac menu bar next to Claude Code and OpenAI Codex, without keeping a terminal tab open, Usage HUD reads the Antigravity CLI’s /quota panel every 30 minutes (or on Refresh now) and labels every reading as official, measured, estimated, or unknown. It doesn’t read Gemini CLI’s own session counters.

Download for Mac (Free) Use built-in /stats first

Free · Usage HUD 1.3.4 · macOS 14 or later, Apple silicon or Intel · signed and notarized by Apple

1. Check usage inside Gemini CLI with `/stats` (free, built in)

Before installing anything new, you can inspect the current terminal session’s requests, input tokens, cached tokens, and output tokens directly inside Gemini CLI:

# Inside an interactive `gemini` session:
/stats
/stats model

What /stats covers and what it misses: /stats is exact for the active terminal process, but it resets when you quit the session, does not aggregate across multiple terminal tabs, and does not sit in the macOS menu bar next to Claude Code or Codex.

2. Put Gemini CLI in the Mac menu bar next to Claude and Codex

Make sure the Antigravity CLI (agy) is installed and signed in with your Google account, and that Node.js 18 or later is installed (node -v).
Download Usage HUD (.dmg), drag it to Applications, and open it.
Click the menu-bar icon → Set up (or Settings → General → Detect again). Usage HUD finds agy and refreshes the Gemini lane every 30 minutes in the background. With only Gemini CLI installed, Set up says the Gemini lane needs the Antigravity CLI.

If you also use coding agents, run '/Applications/Usage HUD.app/Contents/MacOS/CodexUsageHUD' room or connect the built-in MCP server (which_plan_has_room) so your agent knows whether Claude, Codex, or Gemini has the most headroom.

Fair comparison: ways to check Gemini CLI usage on macOS

Feature	Gemini CLI /stats	Usage HUD	CodexBar	ccusage
Price	Free (built in)	Free (optional tip)	Free (open source)	Free (open source CLI)
Google quota	Current terminal session	Antigravity CLI quota in the menu bar, CLI and MCP (30-min refresh)	Supported across multi-provider menu bar	No (Claude / Codex JSONL only)
Claude + Codex + Ollama in one view	No	Yes (Claude, Codex, Gemini, Grok, Ollama)	Yes (cloud providers)	CLI tables only
Confidence labels	Session counters	`official`, `measured`, `estimated`, `unknown`	Raw meters	Local token sum
Agent MCP server (`which_plan_has_room`)	No	Built in (5 read-only tools)	No	No
Requirements	Node.js 18+	macOS 14 or later, Apple silicon or Intel	macOS	Node.js 18+

Get Usage HUD

Free · no account · signed and notarized by Apple

Download for Mac

The download is a notarized disk image. Drag Usage HUD to Applications, open it, then click Set up.

Your Mac: macOS 14 or later, Apple silicon or Intel.
Claude and Codex: Claude Code or Codex signed in. Nothing else to install for those two lanes.
Gemini and Grok: those lanes need Node.js 18 or later. Gemini reads Google’s Antigravity CLI (agy), so sign in there.
Local models: the local lane reads your Ollama logs.

Frequently asked questions

What are the free Gemini CLI usage limits?

Gemini CLI no longer has a free tier. Since June 18, 2026, free personal Google accounts and Google AI Pro and Ultra use the Antigravity CLI (agy), and their limits show in its /quota panel. Gemini CLI now serves Gemini Code Assist Standard and Enterprise, Code Assist for GitHub, and paid Gemini API or Vertex AI keys, which follow those plans’ quotas.

How do I check my Gemini CLI usage in the terminal?

Inside an interactive gemini session, run /stats for session token and request totals or /stats model for per-model breakdown.

How often does Usage HUD refresh the Gemini lane?

Every 30 minutes in the background, and on demand when you click Refresh now. Usage HUD reads the Antigravity CLI’s quota panel, so it needs agy signed in with your Google account and Node.js 18 or later.