Gemini CLI Helper

Run Gemini CLI commands with the correct Node.js version and configuration.

Quick Start

Run a Gemini prompt:

.Codex/skills/gemini-cli-helper/scripts/gemini_run.sh "Your prompt here"

Check Gemini CLI status:

.Codex/skills/gemini-cli-helper/scripts/gemini_status.sh

When to Use This Skill

Invoke this skill when:

• User asks to run Gemini CLI
• User wants to test Gemini trace visibility
• User asks to debug Gemini telemetry
• User mentions "gemini" CLI commands
• Coordinator needs to execute Gemini tasks

Available Scripts

scripts/gemini_run.sh <prompt> [--json]

Run a Gemini CLI prompt with correct Node version.

Usage:

# Simple prompt
.Codex/skills/gemini-cli-helper/scripts/gemini_run.sh "Say hello"

# With JSON output
.Codex/skills/gemini-cli-helper/scripts/gemini_run.sh "Say hello" --json

# Complex prompt with quotes
.Codex/skills/gemini-cli-helper/scripts/gemini_run.sh "List 3 things about AILANG"

scripts/gemini_status.sh

Check Gemini CLI installation and configuration status.

Usage:

.Codex/skills/gemini-cli-helper/scripts/gemini_status.sh

Output:

Gemini CLI Status
━━━━━━━━━━━━━━━━━
Node Version: v22.20.0 (required: v20+)
Gemini CLI: /Users/mark/.nvm/versions/node/v22.20.0/bin/gemini
Version: 0.21.1
GCP Project: multivac-internal-dev
Telemetry: Enabled (GCP Cloud Trace)

Critical Knowledge

Node Version Requirement

Gemini CLI requires Node.js v20 or higher due to regex flag syntax.

# WRONG - Will fail with "Invalid regular expression flags"
gemini --version  # Uses default Node which may be v18

# CORRECT - Use full path with Node v22
/Users/mark/.nvm/versions/node/v22.20.0/bin/node \
  /Users/mark/.nvm/versions/node/v22.20.0/lib/node_modules/@google/gemini-cli/dist/index.js \
  --version

Common Errors

Telemetry Configuration

⚠️ CRITICAL: Telemetry is DISABLED by default!

To enable Gemini CLI traces in AILANG Observatory:

Option 1: Direct to GCP (Recommended)

Create or edit ~/.gemini/settings.json:

{
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "logPrompts": true
  }
}

Or use environment variables:

export GEMINI_TELEMETRY_ENABLED=true
export GEMINI_TELEMETRY_TARGET=gcp
export GOOGLE_CLOUD_PROJECT=multivac-internal-dev

Option 2: Via OTLP Collector

For more control (e.g., sending to multiple backends):

1. Create ~/.gemini/collector-config.yaml:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  googlecloud:
    project: multivac-internal-dev
  otlp/ailang:
    endpoint: localhost:1957
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [googlecloud, otlp/ailang]

2. Enable collector mode in settings:

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "useCollector": true,
    "otlpEndpoint": "http://localhost:4317"
  }
}

Traces appear in:

• GCP Cloud Trace Console
• AILANG Observatory (via composite backend or direct OTLP)

Workflow

1. Check Status First

.Codex/skills/gemini-cli-helper/scripts/gemini_status.sh

2. Run Prompt

.Codex/skills/gemini-cli-helper/scripts/gemini_run.sh "Your prompt"

3. Verify Traces (Optional)

curl -s "http://localhost:1957/api/observatory/traces?limit=10" | jq '.[].service_name' | sort -u

Resources

Reference Guide

See resources/reference.md for:

• Full path configuration
• nvm setup instructions
• Troubleshooting guide
• GCP telemetry details

Notes

• Always use the scripts in this skill instead of direct gemini command
• Scripts handle Node version detection automatically
• Telemetry goes to GCP Cloud Trace, then imported to Observatory
• JSON output mode recommended for programmatic use