gemini-cli/docs/cli/tutorials/shell-commands.md

Execute shell commands

Use the CLI to run builds, manage git, and automate system tasks without leaving the conversation. In this guide, you'll learn how to run commands directly, automate complex workflows, and manage background processes safely.

Prerequisites

• Gemini CLI installed and authenticated.
• Basic familiarity with your system's shell (Bash, Zsh, PowerShell, etc.).

How to run commands directly (!)

Sometimes you just need to check a file size or git status without asking the AI to do it for you. You can pass commands directly to your shell using the ! prefix.

Example: !ls -la

This executes ls -la immediately and prints the output to your terminal. Gemini CLI also records the command and its output in the current session context, so the model can reference it in follow-up prompts. Very large outputs may be truncated.

Scenario: Entering Shell mode

If you're doing a lot of manual work, toggle "Shell Mode" by typing ! and pressing Enter. Now, everything you type is sent to the shell until you exit (usually by pressing Esc or typing exit).

How to automate complex tasks

You can automate tasks using a combination of Gemini CLI and shell commands.

Scenario: Run tests and fix failures

You want to run tests and fix any failures.

Prompt: Run the unit tests. If any fail, analyze the error and try to fix the code.

Workflow:

1. Gemini calls run_shell_command('npm test').
2. You see a confirmation prompt: Allow command 'npm test'? [y/N].
3. You press y.
4. The tests run. If they fail, Gemini reads the error output.
5. Gemini uses read_file to inspect the failing test.
6. Gemini uses replace to fix the bug.
7. Gemini runs npm test again to verify the fix.

This loop turns Gemini into an autonomous engineer.

How to manage background processes

You can ask Gemini to start long-running tasks, like development servers or file watchers.

Prompt: Start the React dev server in the background.

Gemini will run the command (e.g., npm run dev) and detach it.

Scenario: Viewing active shells

To see what's running in the background, use the /shells command.

Command: /shells

This opens a dashboard where you can view logs or kill runaway processes.

How to handle interactive commands

Gemini CLI attempts to handle interactive commands (like git add -p or confirmation prompts) by streaming the output to you. However, for highly interactive tools (like vim or top), it's often better to run them yourself in a separate terminal window or use the ! prefix.

Safety first

Giving an AI access to your shell is powerful but risky. Gemini CLI includes several safety layers.

Confirmation prompts

By default, every shell command requested by the agent requires your explicit approval.

• Allow once: Runs the command one time.
• Allow always: Trusts this specific command for the rest of the session.
• Deny: Stops the agent.

Sandboxing

For maximum security, especially when running untrusted code or exploring new projects, we strongly recommend enabling Sandboxing. This runs all shell commands inside a secure Docker container.

Enable sandboxing: Use the --sandbox flag when starting the CLI: gemini --sandbox.

Next steps

• Learn about Sandboxing to safely run destructive commands.
• See the Shell tool reference for configuration options like timeouts and working directories.
• Explore Task planning to see how shell commands fit into larger workflows.