Connect Gemini to Granular with an API key

Who this is for

This guide is for anyone who wants Granular sessions to use Google Gemini reliably. The recommended setup is simple: create a Gemini API key, put it in the Vault, and let Granular inject it into the terminal environment when an agent runs.

If you have already installed the Gemini CLI and tried its chat login, that can still be useful in your own terminal. It is just not the integration path Granular should rely on for automated chat sessions.

Before you start

• Granular installed on your Mac.
• A Google account that can access Google AI Studio.
• A Gemini API key from Google AI Studio. Google documents GEMINI_API_KEY as the standard environment variable for Gemini API key auth.

Security note: never paste an API key into chat. Store it in the Vault so Granular can inject it privately into the terminal process.

Step 1: create a Gemini API key

1. Open Google AI Studio API keys.
2. Sign in with your Google account.
3. Create a new API key, or copy an existing Gemini API key you want Granular to use.

Google may show project, billing, or key-type options depending on your account. Follow Google’s prompts; the important output is the API key value. You will paste it into the Vault once, then Granular will keep it hidden.

Step 2: add it to the Granular Vault

1. Open Granular.
2. Open Settings and go to Vault.
3. Add a new secret.
4. Paste your Gemini API key as the secret value.
5. Set the environment variable name to GEMINI_API_KEY.
6. Enable the secret for sessions.
7. Scope it to the project where you want to use Gemini, or make it available to all projects if that is your preference.

The name does not need a special suffix. If you see examples that end in _GRANULAR, treat that as an optional naming convention, not a requirement.

Step 3: start a fresh session or reload the environment

Environment variables are read when a terminal process starts. After adding or changing a Vault secret, use a fresh Granular session or reload the session environment so the terminal receives GEMINI_API_KEY.

To check that the variable exists, list names only:

printenv | cut -d= -f1 | grep GEMINI

You should see GEMINI_API_KEY. Do not print the value.

Step 4: use Gemini from Granular

Once the key is injected, Gemini-backed work can authenticate without a browser login or cached CLI session. In practice, that means Granular can run the Gemini process in the non-interactive context it uses for agent turns.

If you are choosing between engines, open the model or agent picker in the prompt area and select the Gemini option when it is available for your setup. If Gemini is not shown or a turn fails with an auth message, re-check the Vault entry: enabled, named GEMINI_API_KEY, and scoped to the current project.

Why Gemini CLI chat login is different

Gemini CLI chat is designed for a person using an interactive terminal. It can ask you to open a browser, complete OAuth, pick an auth method, and rely on local CLI-managed credential files. That model is fine when you are sitting in the terminal yourself.

Granular agent turns are different. They are launched as non-interactive processes that need credentials available at process start. A Vault-injected API key gives that process a stable, repeatable credential. CLI chat login does not provide the same dependable handoff.

This does not mean your Gemini CLI install is broken. It means CLI chat auth and Granular automation are different integration contracts.

Troubleshooting

Granular says Gemini is not authenticated

Check that the Vault entry is enabled, has the environment variable name GEMINI_API_KEY, and is scoped to the current project. Then start a fresh session or reload the environment.

I signed into Gemini CLI but Granular still cannot use Gemini

Use the API key path instead. CLI chat sign-in can depend on browser OAuth and local CLI state; Granular’s reliable path is the environment variable.

I do not see GEMINI_API_KEY in the terminal

List environment variable names only with printenv | cut -d= -f1 | grep GEMINI. If the name is missing, the Vault entry is probably disabled, not scoped to this project, missing its env-var name, or the terminal was opened before the secret changed.

Should I use GOOGLE_API_KEY instead?

Google’s docs say Gemini clients can use GEMINI_API_KEY or GOOGLE_API_KEY. For Granular, prefer GEMINI_API_KEY because it is explicit and avoids confusion with other Google services.

Can I put the key in a .env file?

For Granular, use the Vault. It keeps secrets encrypted and avoids leaving keys in project files that could be committed or shared by accident.

Related