Wiring Gemini CLI into Your Shell and CI — Headless Runs and Session Resume

Resume sessions so you don't throw away context

Even after you close an interactive session, you can pick up where you left off. It's a quiet feature that pays off over time.

# Resume the most recent session
gemini -r "latest"
 
# Resume the latest session with a new instruction
gemini -r "latest" "Check whether any type errors remain"
 
# List sessions, then resume by ID
gemini --list-sessions
gemini -r "abc123" "Finish this PR"

I lean on -r "latest" when I return in the afternoon to a plan I laid out in the morning. It removes the need to re-explain the premise, so the payoff grows with tasks that span a full day.

Pin project assumptions with GEMINI.md

Place a GEMINI.md at the project root and its contents load as context on every run. Put your coding conventions, directory layout, and operations to avoid there, and you stop re-stating background with each instruction.

# GEMINI.md
- This repo is Next.js 16 (App Router) + TypeScript
- Write Japanese comments in polite form
- Always show a diff before editing anything under src/config/

If you edit GEMINI.md in an external editor, run /memory reload mid-session to re-read it. When you update MCP servers or custom commands, /mcp reload and /commands reload refresh those respectively.

Approval modes and sandboxing — the safety valve for automation

The more you delegate file edits and shell execution to the agent, the more the design question "how much do I auto-allow?" matters. Gemini CLI lets you choose that granularity with --approval-mode.

yolo is powerful, but used carelessly it invites irreversible changes. If you run with auto-approval, pair it with -s (--sandbox) to confine it to an isolated environment. Gemini CLI also has Checkpointing, which automatically snapshots project state before the AI modifies files — so an unexpected edit still leaves you room to rewind.

My split is simple: default when experimenting locally, plan when I want to settle direction first, and --approval-mode=yolo --sandbox only where no human is watching, such as CI.

Wire it into your shell and CI — working scripts

Bundle these pieces together and you get automation that holds up in practice. Here's a git hook that reviews the diff before a push.

#!/bin/bash
# .git/hooks/pre-push
set -euo pipefail
 
DIFF="$(git diff origin/main...HEAD)"
if [ -z "$DIFF" ]; then
  exit 0
fi
 
REVIEW="$(printf '%s' "$DIFF" | gemini -m flash -p \
  "If this diff has a security concern or an obvious bug, cite the lines and note it briefly. If it's clean, reply just OK")"
 
echo "----- Gemini review -----"
echo "$REVIEW"
echo "-------------------------"
 
# Anything other than OK nudges the human to look (no hard block)
if ! printf '%s' "$REVIEW" | grep -q "OK"; then
  echo "⚠️ There are notes. Please review before pushing."
fi

In CI, hold to three things: non-interactive, API-key auth, and JSON output. Below, a failing test log is summarized down to the essentials for the job output.

#!/bin/bash
# ci-summarize-failure.sh
set -euo pipefail
 
npm test 2>&1 | tee test.log || true
 
SUMMARY="$(cat test.log | gemini -m flash -o json -p \
  "Give up to 3 root causes of the test failures with a fix hint each. Put prose in the JSON response field" \
  | jq -r '.response')"
 
echo "::group::Test failure summary"
echo "$SUMMARY"
echo "::endgroup::"

The point is not to let Gemini's judgment fail the job. It outputs material to help a human decide, while the final pass/fail stays with the test results themselves. Not handing over too much authority is, in my experience, what keeps automation running over the long haul.

Five places headless runs break, and how to isolate them

A command that worked interactively will usually fall over at least once when you drop it into CI. Here they are, in the order I hit them.

1. The exit code is always 0. When you pipe — gemini -p ... | jq -r '.response' — the shell only looks at the last command in the pipeline. The first stage can fail and the job still goes green as long as jq succeeds. Don't skip set -euo pipefail at the top of the script.
2. Empty stdin sails right through. On a CI box with no TTY, an upstream cat or git diff can return nothing and the run continues; the CLI happily invents plausible prose out of an empty string. Check the byte count right before you hand input over, and abort at zero.
3. The job hangs waiting for a response. A congested network or an oversized input can leave you waiting indefinitely. Rather than trusting a CLI-side setting, wrap the call in timeout and hold the ceiling yourself.
4. A 429 takes down the whole batch. Run things in parallel and you'll reach the rate limit on the free and paid tiers alike. Exponential backoff with jitter, capped at three attempts, turned out to be the easiest balance to live with.
5. JSON parsing breaks. Even with -o json, warnings and progress output can leak onto stderr. Validate with jq -e and fall back to raw text when validation fails, so a malformed response doesn't take the entire job down with it.

I keep a thin wrapper that absorbs all five in each repository's scripts/ directory.

#!/bin/bash
# scripts/gem.sh — shared wrapper for headless calls
set -euo pipefail
 
gem() {
  local prompt="$1" model="${2:-flash}" input attempt=0 raw
  input="$(cat)"
 
  if [ "${#input}" -lt 1 ]; then
    echo "gem: stdin was empty — check the upstream step." >&2
    return 2
  fi
 
  while [ "$attempt" -lt 3 ]; do
    if raw="$(printf '%s' "$input" \
        | timeout 120 gemini -m "$model" -o json -p "$prompt" 2>/dev/null)"; then
      if printf '%s' "$raw" | jq -e '.response' >/dev/null 2>&1; then
        printf '%s' "$raw" | jq -r '.response'
        return 0
      fi
      # Not valid JSON — treat it as raw text
      printf '%s' "$raw"
      return 0
    fi
    attempt=$((attempt + 1))
    sleep $(( (2 ** attempt) + (RANDOM % 3) ))   # exponential backoff + jitter
  done
 
  echo "gem: no response after three attempts." >&2
  return 1
}

Callers just write cat build.log | gem "list up to three fatal errors" flash. Because failures leave a trace in both the exit code and stderr, you can actually trace causes from the CI log afterward. Since adding the empty-input guard, the particular embarrassment of a content-free summary sitting in job output has stopped happening.

Decide model choice by measurement, not by feel

Anyone can develop the sense that flash feels faster. What you can't know without measuring is how much faster it is on your workload. A short script that runs the same prompt across models and reports the median makes that call quick.

#!/bin/bash
# scripts/bench-models.sh <input file> <iterations>
set -euo pipefail
INPUT="$1"; N="${2:-5}"
PROMPT="List up to three fatal errors from this log with a guess at the cause"
 
for MODEL in pro flash flash-lite; do
  TIMES=()
  for _ in $(seq 1 "$N"); do
    START=$(date +%s%3N)
    cat "$INPUT" | gemini -m "$MODEL" -p "$PROMPT" >/dev/null 2>&1 || true
    TIMES+=($(( $(date +%s%3N) - START )))
  done
  MEDIAN=$(printf '%s\n' "${TIMES[@]}" | sort -n | awk '{a[NR]=$1} END{print a[int((NR+1)/2)]}')
  printf '%-11s median %6s ms\n' "$MODEL" "$MEDIAN"
done

On my own Mac, over a wired connection, feeding a build log of roughly 3,900 lines and running ten iterations each, the medians came out approximately as follows. Absolute numbers move with your connection and with model updates, so read the ratios rather than the values.

The error lines themselves came back nearly identical across all three models. What differed was how far each went on the guessed cause: only pro connected the failure back to recent dependency updates. Which means that if you only need the lines pulled out, flash-lite is enough, and pro is worth calling only when you're actually betting on the diagnosis.

In my own setup, the pre-push hook and daily log triage run on flash, article classification batches on flash-lite, and only incident root-cause work goes to pro. That split came from looking at numbers; back when I went by feel, classification was flowing through pro too. Measure once against your own input — it's worth the ten minutes.

Extend its reach with MCP servers and extensions

Gemini CLI supports the Model Context Protocol (MCP), letting you add external tools as hands and feet for the CLI. Configuration is done through subcommands.

# Add a stdio-based MCP server
gemini mcp add github npx -y @modelcontextprotocol/server-github
 
# Add an HTTP-based server
gemini mcp add api-server http://localhost:3000 --transport http
 
# List registered servers
gemini mcp list

If you want to add your own tool server, I cover building one in TypeScript in Building a custom MCP server for Gemini API (TypeScript). The connection steps from the CLI side are collected in Using MCP servers with Gemini CLI.

With extensions, you can distribute and install several settings and tools together.

gemini extensions install https://github.com/user/my-extension
gemini extensions list

Lessons from actually running it

Running Dolice Labs' several sites as an indie developer, it's easy to decide how much to hand the AI based on what feels nice. But once I embedded it, what actually mattered was the design of the constraints.

Since switching to headless execution, my morning log check has gotten noticeably shorter than the manual version. The numbers shift by environment, but the biggest change is that the task shifted from "reading" to "receiving the key points." On the other side, I once ran yolo without a sandbox and got a scare. Ever since, auto-approval and sandboxing go together, always.

Another realization was how much matching the model to the task pays off. Running light work like classification or summarization on pro inflates both latency and cost; leaning on the flash family alone changed how it felt. When you get stuck on an error, troubleshooting Gemini CLI should help you narrow it down.

Gemini CLI, I've come to feel, shows its real worth less through the comfort of conversation and more when it works quietly as one part in your shell. Start by replacing a single log-triage step with gemini -p, and let it settle into your workflow from there. That slower path is, I think, the surer one.

I'm still in the middle of my own trial and error. Thank you for reading — I'd be glad to keep learning alongside you, hands on the keyboard.