Google Gemini CLI¶

Google Gemini CLI is used as an AI agent that can be used directly in a terminal.

I use the Gemini CLI to help generate bash script files and markdown documents for zensical. It is my preferred coding agent at the moment since I already pay for Google One.

I also use the Gemini CLI to provision Proxmox containers using the provided MCP servers.

Installation¶

Config path: ~/.gemini/

npmnpx

npm install -g @google/gemini-cli

npx https://github.com/google-gemini/gemini-cli

gemini

Config¶

Generate a key from Google AI Studio.
Set it as an environment variable in your terminal. Replace YOUR_API_KEY with your generated key.
My current settings.json can be found in my dotfiles repository.

.envManual

export GEMINI_API_KEY="YOUR_API_KEY"

export GEMINI_API_KEY="YOUR_API_KEY"

Syntax Files¶

Syntax files are used to customize the iutput from Gemini.

docs/GEMINI.md

# AI Agent Instructions (AGENTS.md)

This file serves as the primary entry point for AI agents interacting with this repository.

## Project Context & Guidelines

The comprehensive project context, technology stack, and operational workflows have been migrated to the **Conductor** documentation structure. AI agents MUST refer to these files for all development and maintenance tasks:

- **[Product Definition](conductor/product.md)**: Vision, goals, and target users.
- **[Product Guidelines](conductor/product-guidelines.md)**: Agent persona, boundaries, and style guides.
- **[Technology Stack](conductor/tech-stack.md)**: Detailed core infrastructure, automation tools, and MCP server configurations.
- **[Project Workflow](conductor/workflow.md)**: Task lifecycle, project structure, and common commands.

## Tracks and Management

- **[Tracks Registry](conductor/tracks.md)**: Overview of all major tracks and their status.
- **[Tracks Directory](conductor/tracks/)**: Detailed specifications and implementation plans for each track.

---

*Note: This file is now a redirecting index. All substantial instructions should be maintained within the `conductor/` directory.*

AGENTS.md files can also be used to enable the use of other AI agents.

Enable gemini-cli to use AGENTS.md files.

~/.gemini/settings.json

{ "contextFileName": "AGENTS.md" }

MCP Servers¶

MCP servers are used to extract information from my homelab.

GitHub MCP Server¶

The GitHub MCP Server can be used to allow Gemini to interact with GitHub repositories.

~/.gemini/settings.json

{
    "mcpServers": {
        "github": {
            "command": "github-mcp-server",
            "args": ["stdio"],
            "env": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
            }
        }
    }
}

GITHUB_PERSONAL_ACCESS_TOKEN: This environment variable must be set with your GitHub PAT for the github MCP server.

proxmox-mcp-plus¶

The proxmox-mcp-plus can be used to allow Gemini to interact with Proxmox VE.

~/tools/gemini/pve01.config.json

{
    "proxmox": {
        "host": "ENC[AES256_GCM,data:p1JsfjpZkEwwp9GSbw==,iv:19OCjBzm+rggO6JDRuYLdWBAOwifDn1UZFveKFw9jvM=,tag:U0sk0ddTbhXLVlazVJBGzA==,type:str]",
        "port": "ENC[AES256_GCM,data:Upli9w==,iv:85gGYw40tVWeNYdFKWrBy7zwDzXWxki7v1OeCGRCi5o=,tag:9jgzMRH1sc+ewMzlMzwH3g==,type:float]",
        "verify_ssl": "ENC[AES256_GCM,data:9E3aBGY=,iv:fbkdC5uoqzBo9XMJ6C9KQ6Xiigjt3lBvL5P9VU7FXF8=,tag:LMVWTWo20yByl15lsTawHw==,type:bool]",
        "service": "ENC[AES256_GCM,data:fiGp,iv:igDOzuamxL3sJ/x3qE91WkWPaEWjy17WvfIy3jPntbs=,tag:tDaHwo0D5GSjX4dbpgRYYQ==,type:str]"
    },
    "auth": {
        "user": "ENC[AES256_GCM,data:stPJolzn/7g=,iv:QaKasMzFmAFwgdr17zPY8EpJqdvXp7t+kqFs/eBoOUI=,tag:zVZ5+MqE7bgZmSDkwbrthg==,type:str]",
        "token_name": "ENC[AES256_GCM,data:FSCVnjSKyg==,iv:pf3w4QYycx0+BDg/27W6gQoGQwO3Ryon05NHin9DvkY=,tag:zg8AiEGXFLez6al1VM0RRg==,type:str]",
        "token_value": "ENC[AES256_GCM,data:V34BdG52Tp6r8an037LhtkseN0RhTVr1wfaqvtDV6x+ur0p6,iv:WK0gydJJ8iSm/Y7g5Whzas6jgILdGu7okdulRBDmS+o=,tag:URAcl2W+N2s+LuQ+/NO+pw==,type:str]"
    },
    "logging": {
        "level": "ENC[AES256_GCM,data:kRTZMao=,iv:N+qrI5sSg4vQnoNjdhKrYxbhTznSuoDNortnwMqi+ws=,tag:aP9q9fXkLPfK1ZhoGb9GHg==,type:str]",
        "format": "ENC[AES256_GCM,data:edU1YRDAmNOK+WTV9zf/QfTAiFe4qIlXoj39Rz1m4I+uariJGkkmwgy6+Lqx5hyJok1/Cg==,iv:baxSMa5v8FyLrvy7fd4+Mlu+jnR/lhHgDPy48ZPWOyg=,tag:Zak82d+xqosPhGsBLyetWQ==,type:str]",
        "file": "ENC[AES256_GCM,data:HVj8gPfVQ5/Yc02yjUMNgwn596RZ,iv:kHvXTf8OIAXsp/oGIecSavFvgeiQ0cpsw18AjPZvlXc=,tag:UeJ0Pw1+ZFQPY2Y1dSQ8pw==,type:str]"
    },
    "sops": {
        "age": [
            {
                "recipient": "age1x2at6wwq2gks47fsep9a25emdeqd93e3k0gfsswtmhruqrteu5jqjvy7kd",
                "enc": "-----BEGIN AGE ENCRYPTED FILE-----\nYWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB2ZmFHNEVoTGdvUTN1dnNW\nd0ZHSThxWFZRNW1GdldMU1hlU0pTVHBkUFcwCkxRK05vdkxWSVNuVVJtZVllWXlE\nQWpWL212RTZKM0ZIbU5MOG5NSDVNNUkKLS0tIHlMTDlhN2Q5T2swRTFqbGdIQm9h\nSU94Q3ZONENQVVBqejJaYTV0NnVmUFUKlhwFiEVav0Zt3dT4Bfht8FlqQmjGg03b\nmGi/LBqf5BSVhOyxAf8Z2Fd8PnMrm+4SumUUXYOik/TXRs57blycwg==\n-----END AGE ENCRYPTED FILE-----\n"
            }
        ],
        "lastmodified": "2026-01-03T05:07:08Z",
        "mac": "ENC[AES256_GCM,data:5z6FRCjmME6KTEJALOrfyaQbB0Su8NI07+i2lFIrWRqeyRPjTV1HvkJYuR/G26wk20Le92+Q1+C7YdhevXuKEHQe5J8Gmyt+J4TexSP+X1b8S5/3Dg4ZQ3Qm5kJNjcaO/z5caYMz+AfxYM8OEldVggaMtzHD123KAwuTi8bsuxc=,iv:rRiqQpN5AkocheMoi1BPVAjJuZcEydjUM4n8iTTrZ+k=,tag:qLSMV452n4/ME1yneRjoMg==,type:str]",
        "pgp": [
            {
                "created_at": "2026-01-03T05:07:08Z",
                "enc": "-----BEGIN PGP MESSAGE-----\n\nhF4D9lXjpzPw+n0SAQdAUQb8DdMYWe+BKI8Iz6oZzGPOCdebP+o/ANdSLbU3MhIw\nyfwKA8x+lVWzAFDoAPnoVGEDmExBokfBPFAoOOGB3Ic8kIyoxDupfHBiILF/3RDf\n0l4BdrKmEY+okJ+Dz/V3yOUKBJSKsJ3JaQv9vxz609GmcMMUcuSQLcPmKah9hMKZ\n8GZ3vOhgFMD+lGiQgXNw0jbY70gq0PB4LRIbweCutYEJguoSez9v7FFAZypY9lWc\n=9eJb\n-----END PGP MESSAGE-----",
                "fp": "78E2E084522FB8A14C0D9AED800C8DB8B299A622"
            }
        ],
        "unencrypted_suffix": "_unencrypted",
        "version": "3.11.0"
    }
}

~/.gemini/settings.json

{
    "mcpServers": {
        "pve01": {
            "command": "${HOME}/.local/share/uv/tools/proxmox-mcp/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "env": {
                "PROXMOX_MCP_CONFIG": "${HOME}/git/nicholaswilde/homelab/tools/gemini/pve01.config.json"
            }
        },
        "pve04": {
            "command": "${HOME}/.local/share/uv/tools/proxmox-mcp/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "env": {
                "PROXMOX_MCP_CONFIG": "${HOME}/git/nicholaswilde/homelab/tools/gemini/pve04.config.json"
            }
        }
    }
}

Build and Load¶

The Docker image for proxmox-mcp-plus needs to be built and loaded manually.

Code

cd tools/gemini/proxmox-mcp-plus
task load

UniFi Network MCP¶

The UniFi Network MCP allows Gemini to interact with UniFi Network controllers.

~/.gemini/settings.json

{
    "mcpServers": {
      "unifi": {
        "command": "unifi-network-mcp",
        "env": {
          "UNIFI_HOST": "192.168.1.148",
          "UNIFI_USERNAME": "admin",
          "UNIFI_PASSWORD": "password",
          "UNIFI_PORT": "443",
          "UNIFI_SITE": "154bj8wf",
          "UNIFI_VERIFY_SSL": "false",
          "UNIFI_CONTROLLER_TYPE": "auto"
        }
      }
    }
}

Tip

To find the UNIFI_SITE value, check the URL in the UniFi GUI. For example, in https://unifi.l.nicholaswilde.io/network/154bj8wf/dashboard, the site ID is 154bj8wf.

AdGuard Home MCP¶

The AdGuard Home MCP allows Gemini to interact with AdGuard Home for DNS management.

~/.gemini/settings.json

{
    "mcpServers": {
        "adguard": {
            "command": "npx",
            "args": [
                "-y",
                "@fcannizzaro/mcp-adguard-home"
            ],
            "env":{
                "ADGUARD_URL": "http://192.168.2.13",
                "ADGUARD_USERNAME": "admin",
                "ADGUARD_PASSWORD": "password"
            }
        }
    }
}

Home Assistant MCP¶

The Home Assistant MCP allows Gemini to interact with Home Assistant for IoT device control.

Activation¶

Add Integration: Go to your Home Assistant instance, navigate to Settings -> Devices & Services, and click Add Integration. Search for "Model Context Protocol" and add it.
Generate Token: Click on your user profile icon in the bottom left corner of the sidebar. Scroll down to the "Long-Lived Access Tokens" section and click Create Token. Give it a name (e.g., "Gemini MCP") and copy the generated token.

~/.gemini/settings.json

{
    "mcpServers": {
        "homeassistant": {
            "httpUrl": "http://ha.l.nicholaswilde.io:8123/api/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_LONG_LIVED_ACCESS_TOKEN"
            }
        }
    }
}

Nanobanana MCP¶

The Nanobanana MCP is used to watch for repository commit updates.

~/.gemini/settings.json

{
    "mcpServers": {
        "nano-banana": {
            "command": "nanobanana-mcp-server",
            "env": {
                "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
            }
        }
    }
}

Theme¶

The Catppuccin theme can be used to customize the appearance of the Gemini CLI.

Download the mocha flavor of the Catppuccin theme.

wget https://raw.githubusercontent.com/catppuccin/gemini-cli/main/themes/mocha.json -O ${HOME}/.gemini/catppuccin-mocha.json

Add the theme property to your settings.json file.

~/.gemini/settings.json

{
  "ui": {
    "theme": "${HOME}/.gemini/catppuccin-mocha.json"
  }
}

Usage¶

Once installed and authenticated, start interacting with Gemini from the shell. See Gemini CLI Commands for custom commands available in this project.

Example

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> Give me a summary of all of the changes that went in yesterday

Start a chat

gemini

Pipe content to the CLI from stdin

echo "Explain the content of this file docs/README.md" | gemini -p

UniFi Network MCP

> List all connected clients on my network.
> Show me the status of my UniFi devices.
> What are my current firewall rules?

List Models¶

Note

Assuming that your Gemini key is stored in the GEMINI_API_KEY environmental variable and jq is installed.

Code

curl "https://generativelanguage.googleapis.com/v1beta/models?key=${GEMINI_API_KEY}" | jq -r '.models[].name'

Google Gemini CLI¶

Installation¶

Config¶

Syntax Files¶

MCP Servers¶

GitHub MCP Server¶

proxmox-mcp-plus¶

Build and Load¶

UniFi Network MCP¶

AdGuard Home MCP¶

Home Assistant MCP¶

Activation¶

Nanobanana MCP¶

Theme¶

Usage¶

List Models¶

References¶