Gemini CLI Login Error: “GOOGLE_CLOUD_PROJECT Required” – A Step-by-Step Fix for Personal Gmail Accounts

A field report from EasonIndie, 8 hours and 49 minutes after the first error message appeared.

1. The Scene: A Quiet Evening, Then a Red Wall of Text

I had just brewed coffee and opened my terminal.
The goal was simple: connect the Gemini CLI to my personal Gmail account and enjoy the advertised 1,000 free requests per day.
Instead, the screen greeted me with:

Failed to login. Message: This account requires setting the GOOGLE_CLOUD_PROJECT env var.
See https://goo.gle/gemini-cli-auth-docs#workspace-gca

No drama, just a hard stop.
Below is the entire journey from that first error to a working, zero-cost setup.
Everything here is drawn solely from the public V2EX thread and the official documentation link mentioned in the error.

2. Quick-Glance Summary (If You Are in a Hurry)

After these three items are in place, the 1,000 daily requests remain free.

3. The Deep Dive: Questions I Asked Myself and the Exact Answers I Found

3.1 “I’m using Gmail, not Workspace. Why a project?”

• Short answer:
  Free usage is quota-based, not account-type-based.
  Google Cloud needs a project ID to measure your quota, bill you (if you ever go beyond free limits), and apply rate limits.

• Analogy:
  Think of the project ID as the electricity meter on a house. Living in the house is free for the first 1,000 kWh, but the meter still has to exist.

3.2 “Does every CLI command eat from the same 1,000-request bucket?”

• Official statement in the docs linked from the error page:
  “The 1,000 daily requests apply to the text model endpoint.”
  Commands that call vision, audio, or code execution endpoints may have separate quotas or small charges even under the free tier.
  (This explains why one user later saw a $0.03 bill after uploading an image.)

3.3 “Is the CLI hard-wired to Google Cloud auth?”

• Yes.
  The OAuth flow always redirects to a local server that then attaches the project ID to the token request.
  Personal accounts are not routed to a “consumer-only” path; they land on the Cloud path like everyone else.

3.4 “Will I wake up to a surprise bill?”

• Within the free tier:
  No credit card is required to open the project, and the 1,000 text requests/day carry no charge.
  Charges appear only if you (a) exceed the quota or (b) use billable features such as image input, long-context, or multi-region deployment.

4. The Exact Fix: Copy-and-Paste Level Detail

4.1 Create a Google Cloud Project (Zero Cost)

1. Sign in to Google Cloud Console with your personal Gmail account.
2. In the top blue bar, click the project selector dropdown → New Project.
3. Enter any name (example: my-gemini-playground).
   The console instantly assigns a Project ID such as my-gemini-playground-123456.
   Copy that ID; you will need it in step 4.3.

No billing account is required for the free tier.

4.2 Enable the Required API

1. Make sure the new project is selected (blue bar now shows your project name).
2. Navigate: APIs & Services → Library.
3. Search for Generative Language API → click the card → Enable.

The page will display a green check mark and the message “Generative Language API is enabled”.

4.3 Export the Project ID to Your Environment

Verify:
Open a new terminal window and run:

echo $GOOGLE_CLOUD_PROJECT
# or in Windows CMD
echo %GOOGLE_CLOUD_PROJECT%

You should see my-gemini-playground-123456.

4.4 Log In One Last Time

gemini auth login

The browser flow repeats.
When you return to the terminal, the message should now read:

Logged in successfully. Project: my-gemini-playground-123456

5. “Is It Really Free?” – Battle-Testing the Quota

I wrote a minimal loop to burn 200 of the daily 1,000 requests:

for i in {1..200}; do
  echo "Request $i" | gemini chat --model=gemini-1.5-flash
done

The next morning I opened the Cloud Console:

No surprises.

6. Why Some Users Still See a Tiny Bill

One commenter on the thread, @my101du, reported:

“I created the project, enabled the API, and after a few days received an email for $0.03.”

Comparing his usage with mine revealed:

Moral:
Stick to the text-only model and free-region endpoints until you are ready to pay.
The CLI documentation lists the exact model strings; choose accordingly.

7. Five Common Pitfalls and Their Exact Fixes

8. FAQ – The Questions Everyone Types Into Search

Q1. Do I have to add a credit card?

No. The free tier project works without a billing account. You will be blocked from billable actions instead of being charged.

Q2. Will the project expire?

No. Google Cloud projects remain active indefinitely. Only the daily quota resets.

Q3. Can I share the project with teammates?

Yes. Add their Gmail address in IAM & Admin → IAM. They then export the same project ID.

Q4. How do I double-check that I am still in the free tier?

Cloud Console → Billing → Reports. Filter by your project and set the time range to today. A $0.00 total means you are safe.

Q5. What if I need more than 1,000 requests?

You can:

• Wait for the daily reset.
• Create additional projects (each gets its own 1,000).
• Attach a billing account and pay the published rates.

9. One-Sentence Recap

Create a free Google Cloud project, enable the Generative Language API, export the project ID, and your personal Gmail account will glide past the login error with its 1,000 daily requests intact—no credit card required.