Sign in
Documentation
DocsGetting started
View as Markdown

Connect Gemini CLI

Human in the loop approvals for Gemini CLI. Set rules for what runs automatically, and send the rest to your team to approve or deny.

Updated Oct 29, 2026

Human in the loop approvals for Gemini CLI. Let Gemini CLI work on its own, and have a person approve the actions that matter.

withHuman checks every tool call Gemini CLI makes against your approval rules before it runs. Routine calls go straight through. The rest wait for someone on your team to approve or deny them.

You can write rules like:

Let Gemini CLI refund customers up to $20 automatically. Send larger refunds to the support team to approve first.

What you can do

  • Hold the calls that matter. Let reads run, and hold emails, deploys, refunds and record changes for a person.
  • Approve from anywhere. Review requests in the web app, Slack, Discord, email or the withHuman phone app for iPhone or Android.
  • Ask the right people. Send requests to teams, with escalation levels and working hours.
  • Decide routine calls automatically. Approve or deny them with your own webhook, or with an AI judge.
  • Give Gemini CLI your tools. Gemini CLI uses them through the withHuman MCP gateway, without their credentials.
  • Use one set of rules for every agent. The same rules cover Claude Code, Codex, OpenClaw, Hermes and your own agents.
  • See every tool call. The audit log records every call Gemini CLI makes, and who approved it.

Before you start

You'll need:

  • Gemini CLI on macOS or Linux. The extension doesn't work on Windows.
  • An agent in withHuman for Gemini CLI to connect to, and permission to issue credentials for it. Owners and admins have it. See Agent creation.
  • Approval rules for its calls. See Set up approval pipelines.

1. Get an API key

Open Agents, select your agent and select New instance. Choose Generate an API key, enter an instance name such as gemini-laptop, and select Generate API key.

Copy the Agent API key before you leave the page. It's shown only once.

2. Install the extension

bash
gemini extensions install https://github.com/withHumanAI/withHuman

Gemini CLI asks for two settings:

  • Agent key: paste the key from step 1.
  • withHuman address: leave it empty for hosted withHuman. For a self-hosted deployment, enter its address, such as https://approvals.example.com.

Start a new Gemini CLI session to use the extension. The first tool call downloads the withHuman CLI, which the extension runs to reach withHuman.

What to expect

Every tool call goes to withHuman before it runs. Calls your rules approve run at once. Calls that need a person wait in the Review queue for up to a week. Keep the session open while a call waits.

Gemini CLI's own confirmations still apply, so an approved call may still ask you to confirm it in Gemini CLI.

On hosted withHuman, the extension also adds the MCP Gateway as an MCP server named withhuman-gateway, so Gemini CLI can use the tools you grant your agent there.

Check it works

Start Gemini CLI and ask it to run a harmless command your rules send to a person:

text
Run the shell command: echo hello from withHuman

The call waits, and the request appears in the Review queue. Approve it and check the command runs. Try again and deny it to check the call is blocked.

Security and footprint

  • Sends: each tool call's name and arguments to your withHuman organization.
  • Stores: the agent key in Gemini CLI's extension settings, kept in your system keychain, and the withHuman address beside it.
  • Runs: the withhuman CLI, once for each tool call. It sees only the environment variables it needs, never your other API keys.
  • Downloads: a pinned version of the withHuman CLI from downloads.withhuman.ai, on the first tool call. The extension checks it against a checksum it ships with.
  • Adds to Gemini CLI: the withhuman-gateway MCP server, which sends the agent key to your withHuman address, and the withhuman, withhuman-cli and withhuman-pipelines skills. Removing the extension removes them.

Update or remove

Update the extension:

bash
gemini extensions update withhuman

Change the API key or address:

bash
gemini extensions config withhuman

Remove the extension:

bash
gemini extensions uninstall withhuman

Removing the extension doesn't revoke its key. If you won't use it again, revoke the instance on the agent's Instances tab.

Connect with the withHuman CLI instead

To sign in through your browser instead of pasting a key, leave Agent key empty when you install the extension. Then connect with the withHuman CLI:

bash
curl -fsSL https://downloads.withhuman.ai/install.sh | sh -s -- agent install gemini

Troubleshooting

  • Calls run without approval: Gemini CLI runs a call when the extension can't start. Check that hooks are turned on in Gemini CLI's settings (hooksConfig.enabled), that you started a new session, and that gemini extensions list shows withhuman enabled.
  • Every call is denied because the key was refused: The key may have expired or been revoked, or the agent archived or disabled. Generate a new key and set it with gemini extensions config withhuman.
  • Every call is denied because the withHuman CLI couldn't be downloaded: The first call needs to reach downloads.withhuman.ai. Check your network, or install the CLI yourself.
  • On Windows, every call is denied: The extension needs macOS or Linux. Remove the API key with gemini extensions config withhuman, or uninstall the extension.