---
title: Gemini CLI
description: Gemini CLI connector wires settings.json hooks (BeforeAgent, BeforeModel, BeforeTool, AfterTool, AfterAgent) plus the native OTLP exporter pointing at the gateway.
keywords:
  - DefenseClaw Gemini CLI connector
  - Gemini CLI hooks
  - Gemini CLI OTLP
  - Gemini CLI observability
---

The Gemini CLI connector wires DefenseClaw into [Google's Gemini CLI hooks](https://github.com/google/generative-ai-tools) and points the agent's native OTLP exporter at the gateway so traces, metrics, and logs land in one place.

## Setup

```bash
defenseclaw setup geminicli
```

Pins `claw.mode=geminicli`, wires hooks against `~/.gemini/settings.json` and points Gemini's native OTLP exporter at the gateway. **There is no proxy-enforcement path** for Gemini CLI — blocking happens hook-side via the documented `BeforeAgent`, `BeforeModel`, `BeforeTool`, `AfterTool`, and `AfterAgent` events. Gemini CLI has no native ask surface, so HITL approvals downgrade to confirm verdicts in the DefenseClaw TUI.

#### What `setup geminicli` actually does

The wrapper accepts exactly three flags. The underlying guardrail config falls back to the values DefenseClaw ships with — schema-defined in [`internal/config/config.go`](https://github.com/cisco-ai-defense/defenseclaw/blob/main/internal/config/config.go) and documented on the [Defaults page](/docs/defaults).

| Flag | Default | What it does |
| --- | --- | --- |
| `--yes / -y` | off | Skip the confirmation prompt (alias: `--non-interactive`, `--accept-defaults`). |
| `--restart / --no-restart` | `--restart` | Bounce `defenseclaw-gateway` after applying changes so the new hooks + OTLP env vars wire in. |
| `--with-local-stack / --no-local-stack` | `--no-local-stack` | Also bring up the bundled Prom/Loki/Tempo/Grafana stack via `setup local-observability up`. |

Pinned by the alias regardless of flags: `claw.mode=geminicli`, `guardrail.connector=geminicli`, `guardrail.mode=observe`, `guardrail.scanner_mode=local`, `guardrail.judge.enabled=false`, `guardrail.detection_strategy=regex_only`. To tune any of those after install, use [`defenseclaw setup guardrail --connector geminicli`](/docs/setup/guardrail) — see the variations below.

#### Common variations — pick the recipe that fits your phase

<Tabs items={['Standard', 'Local stack', 'Add scanning rigor', 'Hook-side enforcement']}>

<Tab value="Standard">

```bash
defenseclaw setup geminicli
```

Confirms once, wires the hooks against `~/.gemini/settings.json`, points OTLP at the gateway, restarts the gateway. Findings flow to `~/.defenseclaw/gateway.jsonl` and the TUI; no traffic is intercepted, no requests are blocked. Pass `--yes` to skip the confirmation in CI.

</Tab>

<Tab value="Local stack">

```bash
defenseclaw setup geminicli --yes --with-local-stack
```

Same as standard but also runs `setup local-observability up` so Prom/Loki/Tempo/Grafana come up locally — particularly useful for Gemini since native OTLP feeds traces and metrics directly into Tempo and Prometheus. See [Local observability](/docs/observability/local-observability).

</Tab>

<Tab value="Add scanning rigor">

```bash
export DEFENSECLAW_LLM_KEY=<your-key>

defenseclaw setup geminicli                               # base alias first
defenseclaw setup guardrail \
  --connector geminicli \
  --rule-pack strict \
  --scanner-mode both \
  --detection-strategy regex_judge \
  --judge-model anthropic/claude-sonnet-4-20250514 \
  --judge-api-key-env DEFENSECLAW_LLM_KEY \
  --restart
```

The alias keeps the connector pinned; the follow-up `setup guardrail` swaps in the strict rule pack, runs both local + [Cisco AI Defense](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html) scanners, and turns the LLM judge on as a second-pass adjudicator on regex-flagged events.

</Tab>

<Tab value="Hook-side enforcement">

Gemini CLI has no proxy enforcement, but its hooks themselves can block. After `setup geminicli`, edit `~/.defenseclaw/config.yaml` and set the per-connector hook mode:

```yaml
connector_hooks:
  geminicli:
    enabled: true
    mode: action          # observe (default) | action
    fail_mode: open       # open | closed
```

Then `defenseclaw setup guardrail --restart` to re-wire. With `mode: action`, Gemini's lifecycle hooks block on findings; HITL approvals downgrade to confirm verdicts in the DefenseClaw TUI since Gemini CLI has no native ask surface — make sure operators are reachable there.

</Tab>

</Tabs>

#### Decision aids — should I turn this on?

<Cards>
  <Card href="/docs/hitl" title="Human-in-the-loop (HITL)" description="Per-connector ask matrix. Gemini CLI downgrades to confirm verdicts in the TUI / audit log since it has no native ask." />
  <Card href="/docs/setup/guardrail#every-flag" title="Full setup guardrail flag reference" description="All ~20 flags you can pass via `setup guardrail --connector geminicli` after the alias has pinned things." />
  <Card href="/docs/defaults" title="Defaults & rule packs" description="What permissive / default / strict actually ship, and which one matches your risk tolerance." />
  <Card href="/docs/setup/guardrail#watch-the-interactive-flow" title="Interactive wizard" description="Animated terminal demo of the prompt-by-prompt setup flow — the safest path the first time." />
</Cards>

<Callout>
Not sure what to pick? Run `defenseclaw setup guardrail` (no flags) — the [interactive wizard](/docs/setup/guardrail#watch-the-interactive-flow) walks you through every choice with safe defaults pre-selected and inline help. The [Prompt → flag mapping](/docs/setup/guardrail#prompt--flag-mapping) table gives you the CI-shaped command for the same configuration.
</Callout>

## Files DefenseClaw will modify

<Files>
  <Folder name="~/.gemini" defaultOpen>
    <File name="settings.json (hooks + telemetry blocks)" />
  </Folder>
  <Folder name="~/.defenseclaw" defaultOpen>
    <Folder name="hooks">
      <File name="geminicli-hook.sh" />
    </Folder>
  </Folder>
</Files>

## Hook capabilities

<HookEventsList connector="geminicli" />

<Callout>
Gemini CLI has no native human-approval surface. HITL approvals downgrade to confirm verdicts in the DefenseClaw TUI / audit log.
</Callout>

## Telemetry channels

<Flow
  direction="LR"
  caption="Hooks cover the lifecycle; native OTLP delivers traces and metrics out-of-band."
>
  <Node id="gemini" kind="agent">Gemini CLI</Node>
  <Node id="hooks" kind="connector">{`BeforeAgent / BeforeModel /\nBeforeTool / AfterTool / AfterAgent`}</Node>
  <Node id="otlp" kind="connector">Native OTLP exporter</Node>
  <Node id="gateway" kind="gateway">defenseclaw-gateway</Node>
  <Edge from="gemini" to="hooks" />
  <Edge from="hooks" to="gateway" />
  <Edge from="gemini" to="otlp" />
  <Edge from="otlp" to="gateway" />
</Flow>

## Disable

```bash
defenseclaw setup guardrail --disable
```
