Gemini CLI

Make Google's Gemini CLI ask a person before it runs a shell command or changes a file: a BeforeTool hook that fails closed, the MCP server, and headless runs in CI.

Gemini CLI asks at the terminal before it runs a command or changes a file. That works while you sit there. For a headless gemini -p run in a script or CI, or a long session in YOLO mode, nobody is there to answer. A BeforeTool hook sends each of those calls to your inbox instead: answer from your phone, Slack or email, let rules answer the routine ones, and keep every answer on one record.

The quick way: one command

With Node.js on the computer it runs on, this does steps 1 and 3 for you. It opens the browser to sign in (or to make your free account), saves an agent key on this computer, and adds the approval hook to ~/.gemini/settings.json, keeping the old file beside it:

npx -y https://variantgate.com/sdk/variantgate-agent-0.3.0.tgz setup gemini

Restart Gemini CLI and ask it to run echo hello in the shell: it waits until you approve it in the inbox. A file it cannot change safely, such as one with comments or one that links elsewhere, is left alone, and the command prints the entry to add yourself. The steps below do the same by hand and add the MCP server, which the command leaves out.

1. Create a key

Sign in, open Agents and create a key for Gemini CLI. Copy it: it is shown once. Put it in your shell profile, such as ~/.zshrc, as export VARIANTGATE_KEY=….

2. Add the server and the skills

Add the approvals server to ~/.gemini/settings.json. Gemini CLI fills in $VARIANTGATE_KEY from your environment, so the key never sits in the file:

{
  "mcpServers": {
    "variantgate": {
      "httpUrl": "https://api.variantgate.com/mcp",
      "headers": { "Authorization": "Bearer $VARIANTGATE_KEY" }
    }
  }
}

The skills teach the model when to ask and how. Gemini CLI reads ~/.agents/skills, the same folder Codex uses:

curl -fsSL https://variantgate.com/skills/asking-for-approval/SKILL.md --create-dirs -o ~/.agents/skills/asking-for-approval/SKILL.md
curl -fsSL https://variantgate.com/skills/adding-approvals-to-code/SKILL.md --create-dirs -o ~/.agents/skills/adding-approvals-to-code/SKILL.md

The server adds four tools, described on the MCP server page. They rely on the model choosing to ask. The hook in the next step does not.

3. Put commands and file changes through approval

Install the variantgate command (more on the SDK page):

npm install -g https://variantgate.com/sdk/variantgate-agent-latest.tgz

The hook reads VARIANTGATE_KEY from the environment Gemini CLI starts from.

Or run variantgate login once on this computer instead. It opens the browser, you check a code and press Connect, and it saves a new agent key in ~/.config/variantgate/credentials.json, readable only by you. The hook uses that key, with the API address it was made for, whenever VARIANTGATE_KEY is not set. The MCP server still needs the key from step 1.

Then add the hook next to the server in ~/.gemini/settings.json:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "^(run_shell_command|write_file|replace)$",
        "hooks": [
          {
            "name": "variantgate",
            "type": "command",
            "command": "VARIANTGATE_GEMINI_HOOK_WAIT=120 variantgate hook gemini",
            "timeout": 150000
          }
        ]
      }
    ]
  }
}

The hook runs before every matching call and waits for a person. An approval lets the call go on; a denial blocks it, and the reason goes back to the model as the tool’s error. Each call becomes a request with an action name that rules can match. The built-in tools get the same names the Claude Code hook uses, so one rule covers both:

shell.run
run_shell_command: Run the command: …
file.write
write_file: Write the file …
file.edit
replace: Edit the file …
web.fetch
web_fetch: Fetch: … (the prompt with its addresses)
web.search
google_web_search: Search the web for: …
mcp.<server>.<tool>
A tool from an MCP server, named from Gemini CLI's own record of the server and tool
tool.<name>
Any other tool: Use the <name> tool

What Gemini CLI does when a hook fails

We checked this with Gemini CLI 0.70, because it decides how safe the setup is. A hook that exits with an error, or is still running when its timeout ends, does not block the call: Gemini CLI shows a warning and runs the tool. So the variantgate hook always answers with an explicit allow or deny, and never with an error:

  • It waits VARIANTGATE_GEMINI_HOOK_WAIT seconds for a person (40 if you leave it out, inside Gemini CLI’s default 60-second timeout), then withdraws the request and denies the call. The hook cannot see its own timeout, so change both together: keep the timeout, in milliseconds, at least 20 seconds longer than the wait. A longer wait without a longer timeout lets calls through.
  • If the service cannot be reached, or stops answering, the call is denied within about ten seconds of the end of the wait, and a request it already opened is taken back. It never answers “ask”: in a headless run that waits for a terminal that isn’t there.
  • A call the agent key may not ask about is denied, with the reason.

A hook that cannot start at all, because Node or the variantgate command is missing from the PATH Gemini CLI sees, also lets the call through. Check it once after setup: run a harmless command, deny it in the inbox, and make sure Gemini CLI says the tool execution was blocked.

Your own prompts and YOLO mode

The hook runs before Gemini CLI’s own policy check, and an approval from the inbox does not skip it. In the default mode at the terminal you would answer twice, so the hook pays off where nobody is at the terminal:

  • A headless gemini -p run in the default mode leaves out the tools that need a confirmation, the shell among them. To let it run commands at all, run it with --approval-mode=yolo and let the hook be the person who answers.
  • In YOLO mode every call the matcher misses runs without asking. For those runs, match every tool except the ones that only read, so a tool added later, or one from a new MCP server, is asked about too:
"matcher": "^(?!(read_file|read_many_files|list_directory|glob|grep_search|write_todos|mcp_variantgate_(request_approval|check_approval|withdraw_request|report_outcome))$)"

The matcher is a JavaScript regular expression tested against the tool name, and it leaves out the approvals server’s own tools. MCP tools are named mcp_<server>_<tool>, so give no other server a name that starts with variantgate_: its tools could end up with the same names.

In GitHub Actions

Commit the hook in the repository’s .gemini/settings.json with the matcher above, and give the job both keys:

- name: Install Gemini CLI and the approvals hook
  run: npm install -g @google/gemini-cli https://variantgate.com/sdk/variantgate-agent-latest.tgz
- name: Let Gemini CLI fix the build
  run: gemini -p "Fix the failing test and commit the fix" --approval-mode=yolo
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
    VARIANTGATE_KEY: ${{ secrets.VARIANTGATE_KEY }}
    GEMINI_CLI_TRUST_WORKSPACE: "true"

Project hooks only run in a trusted folder, which GEMINI_CLI_TRUST_WORKSPACE says the checkout is. On GitHub Actions, Gemini CLI also strips environment variables whose names contain KEY, TOKEN, SECRET and similar words from what hooks see. The hook then stops with an error that blocks every call, which is safe but useless, so let the key through in the same settings file:

{
  "security": {
    "environmentVariableRedaction": { "allowed": ["VARIANTGATE_KEY"] }
  }
}

Gemini CLI warns about project hooks it has not seen before and runs them. Treat a change to that file like a change to the pipeline: whoever can edit it can remove the hook.

4. Try it

Ask Gemini CLI to run a harmless command. Approve the request in the inbox and the command runs; deny the next one and check that Gemini CLI reports it as blocked. Writing rules for the routine commands keeps the questions to the ones that matter, and the tool risk checker sorts an MCP server’s tools into the ones that only read and the ones that change something. To refuse what must never run before it reaches anyone, the Gemini CLI policy builder writes a policy file of allow, ask and deny rules: Gemini CLI checks it before the hook, so a refused call never reaches your inbox. If you already have one, the Gemini CLI policy checker shows which of its rules Gemini CLI skips or lets something outrank.