Gemini CLI Bash Tool: Setup, Commands, and Safety Controls

The Gemini CLI Bash tool, officially named run_shell_command, lets Gemini CLI execute shell commands on your computer or in a configured environment. That changes the operating model from “AI suggests a command” to “AI may invoke a command with real permissions.” This guide shows how to install and authenticate Gemini CLI, choose between direct commands and task-based execution, and validate what actually happened.

Use !git status when you already know the command you want to run. Ask Gemini to run tests and inspect failures when later steps depend on intermediate output. In both cases, treat the process exit code, working directory, output, and required artifacts as the evidence of success. Gemini’s explanation is useful context, but it is not a substitute for process validation.

Gemini CLI documentation changes over time. Check the installed release with gemini --version before relying on a runtime requirement, default, approval behavior, or configuration setting.

What the Gemini CLI Bash tool does

run_shell_command executes commands through the system shell. The documented default is bash -c on non-Windows systems and powershell.exe -NoProfile -Command on Windows, subject to configuration and release-specific behavior. The result can include the command, working directory, standard output, standard error, exit code, and, when relevant, a background process ID. See the official shell-tool reference.

There are three practical interaction patterns:

• Natural-language task: Describe a bounded objective, such as running the project tests and listing failing test names. Gemini can choose and sequence commands based on intermediate results.
• Direct command: Prefix a known command with !, such as !git status or !ls -la. The command is passed to the shell.
• Shell Mode: Enter ! by itself to switch into a mode where subsequent input is treated as shell commands. Use the command reference for the current exit behavior.

Direct passthrough is efficient when the command is already known. A task description is more useful when the next command depends on what the previous command finds. The ! prefix does not remove shell permissions or approval controls, so consequential changes still need a review path.

Install Gemini CLI and check the version

Current official installation documentation lists Node.js 20.0.0 or newer. Older CLI releases may have had different requirements, so do not copy an older tutorial without checking the release you intend to use. The npm path below installs the current stable package when no release channel is specified.

1. Check the runtime and package manager:

node --version
npm --version

2. Install the stable package globally and verify the CLI:

npm install -g @google/gemini-cli
gemini --version

The official guide also lists Homebrew, MacPorts, Anaconda-based installation, and npx. Start Gemini CLI from the project directory where you intend to work. If gemini is not found, check npm’s global executable directory and the system PATH before reinstalling.

For troubleshooting or comparing machines, record the environment that produced the result:

• node_version
• npm_version
• gemini_cli_version
• install_channel
• operating_system
• shell
• sandbox_mode

This record helps separate a command failure from a release, installation channel, shell, or sandbox difference.

Choose authentication for the environment

The official authentication guide documents Google-account login, Gemini API keys, and Vertex AI. Choose according to the environment rather than treating one method as universally best.

• Local workstation: Google-account login is suitable for many individual users. Follow the browser sign-in flow. The documented Google-account credentials are cached locally for later sessions.
• Headless job or CI: Configure a supported non-interactive credential, such as GEMINI_API_KEY, through the CI platform’s secret store. Do not place the key in a prompt, committed .env file, shell history, task comment, or captured output.
• Google Cloud-managed environment: Vertex AI may fit an organization that needs Google Cloud project controls, IAM, regional configuration, or existing cloud governance. Configure GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION, then configure the required authentication method.

Company, school, Workspace, and certain Gemini Code Assist cases may require a Google Cloud project. Individual Google accounts generally do not. Confirm project, location, permissions, quotas, credential handling, and organizational requirements with the relevant administrator. Do not assume API keys or service-account files have the same caching behavior as Google-account login. Processes launched from a shell may be able to read exported variables.

Run commands and verify what happened

A reliable shell run has separate stages: define the request, make the policy or approval decision, execute the process, inspect the structured result, validate required conditions, and assign follow-up. This separation prevents a plausible AI summary from being mistaken for a passing command.

For a known command, enter !ls -la or !git status. For dependent steps, ask for a bounded task such as, “Run the project tests and list the failing test names.” After execution, inspect the working directory, command, standard output, standard error, exit code, and any background process identifier. Non-empty output does not prove success, and a positive summary does not turn a nonzero exit code into a pass.

For a test run, define the gate before execution. A useful minimum is exit_code == 0 plus the presence of the expected test report or artifact. If either condition fails, preserve the failure and route it to the developer or CI owner. Chained commands are subject to command validation, so keep every component within the intended permission boundary.

Handle interactive commands and long-running sessions

Gemini CLI documents PTY-based interactive shell support for commands such as editors, terminal monitors, and interactive Git operations. The setting tools.shell.enableInteractiveShell controls this behavior. Interactive defaults have changed across versions and documentation, so verify the installed release rather than assuming interactive commands are always blocked or always enabled. Google announced PTY-based support beginning with Gemini CLI v0.9.0, while the current shell documentation is the better reference for present configuration.

Before starting an interactive command, confirm that an operator is available to answer prompts and finish the session. This is different from a headless CI job, which should terminate predictably. For a development server or watcher, record the process or session identifier, use /shells to inspect active sessions, and assign someone to stop it. A background process should never be left without an owner or expected exit condition.

Set command policies and sandbox boundaries

The policy engine supports allow, deny, and ask_user decisions, with tool matching, command-prefix or regular-expression matching, argument patterns, and priority rules. Actual results depend on approval mode, policy files, trusted-folder settings, and other configuration. Use the current policy-engine reference rather than treating the older tools.exclude setting as the primary control. That setting is marked deprecated.

A practical command policy distinguishes impact:

• Read-only inspection: Use a lighter gate when the working directory and data exposure are understood.
• Tests and formatting: Allow or confirm them within a scoped workspace, while checking their scripts and dependencies.
• Package installation and Git mutations: Require review because install scripts, hooks, commits, and branch changes can alter state.
• Production actions, destructive deletion, permission changes, database operations, and deployments: Deny by default or route through a separate human-controlled process.

Gemini CLI also supports optional sandboxing through supported mechanisms such as Docker, Podman, or macOS Seatbelt, depending on the environment and release. Check the selected mechanism, writable mounts, network access, privileges, credential exposure, and host integrations. A sandbox can reduce host exposure, but its practical boundary is determined by its configuration.

For sandbox methods and launch options, consult the sandbox reference. For an untrusted repository, verify mounts and network behavior before allowing commands that install packages, access credentials, or communicate with external services.

Make shell work reviewable in local teams and CI

A prompt or conversation is not the same thing as a command execution. One request can create multiple tool calls, and a retry is another attempt. Store one command-run record for each execution attempt. The following is an editorial example schema, not a Gemini CLI-published audit model:

{
  "run_id": "exec-7f31",
  "session_id": "session-204",
  "command_sequence": 2,
  "working_directory": "./service",
  "cli_version": "record-installed-version",
  "repository_commit": "commit-sha",
  "approval_decision": "approved",
  "sandbox_mode": "record-configured-mode",
  "policy_revision": "policy-12",
  "started_at": "record-start-time",
  "finished_at": "record-finish-time",
  "exit_code": 1,
  "stdout_artifact_uri": "redacted-artifact-location",
  "stderr_artifact_uri": "redacted-artifact-location"
}

Keep raw command evidence separate from Gemini’s interpretation. A wrapper such as tee or script may capture terminal output, but it does not by itself guarantee complete, structured, tamper-resistant, or centrally retained logs. Decide what to retain, redact secrets, restrict access, and document the retention period.

Trigger	AI job	Validation	Action or fallback
Local task	Run scoped steps and summarize output.	Check directory, approval, exit code, and changed files.	Continue locally, or stop and confirm scope before rerunning.
CI test run	Run the authorized task and summarize failures.	Require expected commit, zero exit code, required artifacts, and secret checks.	Publish CI status; send missing artifacts or failures to the CI owner.
Project-management report	Summarize validated results or classify likely failures.	Check fields, commit identity, redaction, and duplicate controls.	Write only through a separately implemented integration; route ambiguity to a reviewer.

For CI, pin the Gemini CLI version, use non-interactive authentication, define allowed commands, retain logs and artifacts, and make success depend on deterministic checks. Generate an orchestrator-owned execution ID before invoking the command. Enforce uniqueness with a database constraint or transactional upsert. A read-then-insert check can race when concurrent retries run.

Keep an attempt number separate from the logical operation. Do not deduplicate only by command text, task ID, or date. A command attempt, test-suite run, individual test failure, and aggregate task summary are different data grains and should remain distinguishable.

Teams defining bounded AI roles and review processes may find AI agent design and implementation relevant. This is a general service resource, not a Gemini CLI logging or integration feature.

Can Gemini CLI send command results to ClickUp?

The official sources reviewed do not establish a native Gemini CLI connector that automatically writes run_shell_command results to ClickUp. Treat ClickUp reporting as a proposed external pattern using a separately implemented script, webhook, orchestrator, or API integration. Verify current ClickUp API access, authentication, rate limits, task-update behavior, and retention requirements before building it.

A cautious illustrative sequence is:

1. An operator or CI job starts a run and receives a unique execution ID.
2. The external integration stores the repository commit, working directory, exit code, approval decision, and redacted artifact references.
3. Optional AI processing summarizes validated logs or suggests a failure category.
4. Deterministic checks verify required fields, process status, commit identity, and redaction.
5. A human-approved, idempotent update is posted to the relevant task.

Unexpected commits, ambiguous failures, suspected secret exposure, network or privilege requests, and duplicate-write risks should enter a review state rather than silently changing task status. Use a database-enforced unique key or transactional upsert for the execution record before performing a task update.

ClickUp’s Code Testing Agent listing describes high-level capabilities including test-suite execution, failure identification, severity ranking, and reporting to ClickUp tasks. It does not document a Gemini CLI connection, API payloads, retry behavior, idempotency guarantees, or field mappings. Similarly, any ClickUp coding-agent product naming or availability should be checked against current ClickUp documentation before being presented as a supported service.

Keep the records at the correct grain. A command attempt is not a test-suite run, an individual test failure, or an aggregate task summary. One task may summarize multiple runs, but each underlying execution should retain its own identifier and evidence. Teams designing a separate workflow can review ClickUp setup and automation; that service page does not establish a native Gemini CLI writeback.

Frequently asked questions

What Node.js version does Gemini CLI require?

Current official installation documentation lists Node.js 20.0.0 or newer. Check the requirement for the exact CLI release you install.

Does the ! prefix bypass approval controls?

No. It passes a known command to the shell. The command still has shell permissions and potential impact, and its behavior remains subject to the configured policy and approval settings.

Are interactive shell commands enabled by default?

Behavior is version- and configuration-dependent. Check tools.shell.enableInteractiveShell for the installed release, confirm an operator is present, and define how the session will end.

How do I know a command succeeded?

Inspect the exit code, stderr, working directory, expected output, and required artifacts. Treat a nonzero exit code as a failure even if Gemini’s summary sounds positive.

How do I stop a background process?

Use /shells to inspect active sessions and identify the relevant process or session identifier. Stop the server or watcher according to the current CLI behavior, then confirm that the session has closed.

Does Gemini CLI provide a guaranteed audit log?

No such guarantee is established by the reviewed shell documentation. If auditability matters, design and test your own record, redaction, access-control, retention, and tamper-detection process.

Does Gemini CLI automatically update ClickUp tasks?

The reviewed official sources do not establish a native connector. Any ClickUp writeback should be implemented and verified as a separate integration with explicit validation, ownership, and duplicate prevention.