Gemini CLI icon

Gemini CLI

Use Google Gemini CLI to execute AI-powered coding tasks with multimodal capabilities
Join our community

Actions7

Overview

The "Execute Plan" operation of the Gemini CLI node allows users to execute a previously approved AI-generated execution plan. This plan consists of multiple ordered steps, each describing a task such as running commands, modifying files, or performing code analysis. The node runs these steps sequentially, updating the plan's status and step statuses accordingly.

This operation is beneficial in scenarios where complex coding or project tasks are broken down into actionable steps by an AI assistant, and then automatically executed in a controlled environment. For example, a developer might generate a plan to refactor a codebase, add error handling, and run tests; after approving this plan, they can use this node to carry out the plan without manual intervention.

Practical examples:

  • Automating multi-step code modifications suggested by an AI.
  • Running a sequence of shell commands and file operations defined in a plan.
  • Executing detailed project setup or deployment instructions generated by AI.

Properties

Name Meaning
Plan ID The unique identifier of the execution plan to run. Must refer to an existing, approved plan.
Model The Gemini AI model to use for any AI interactions during execution. Options: "Gemini 2.5 Pro" (most capable), "Gemini 2.5 Flash" (faster, efficient).
Max Turns Maximum number of conversation turns allowed (not directly used in execution but part of general config).
Timeout Maximum time in seconds to wait for each Gemini CLI command to complete before aborting.
Project Path Directory path where the Gemini CLI will run. If empty, defaults to current working directory. This sets the context for file access and command execution.
Output Format Format of the output data. Options include: "messages" (raw message array), "plan" (execution plan structure), "plan_status" (progress and status), "structured" (detailed object with messages, summary, result, metrics), "text" (final result text only).
Additional Options Collection of extra settings including API key (for Gemini API authentication), whether to use Vertex AI, system prompt for additional context, and debug mode toggle.
Tools Configuration Settings to enable built-in tools like filesystem access, shell commands, web fetch/search, security modes (safe, auto-approve, sandbox), and checkpointing of session state.
MCP Servers Configuration for external MCP servers to extend functionality, including connection type, commands, environment variables, tool inclusion/exclusion, trust level, and working directory.

Output

The output JSON structure depends on the selected "Output Format":

  • messages: An array of all exchanged messages during execution, including user prompts, assistant responses, and errors.
  • plan: The full execution plan object, including metadata and step details.
  • plan_status: Summary of the plan execution progress, including counts of completed and failed steps, and final status.
  • structured: A comprehensive object containing:
    • messages: All messages exchanged.
    • summary: Counts of user, assistant, and error messages plus a flag indicating if a result exists.
    • result: The final textual result from Gemini CLI.
    • metrics: Execution duration, number of turns, and success flag.
    • configuration: Details about model, enabled tools, security mode, checkpointing, MCP servers, and project path.
  • text: Only the final result text string.

If binary data were involved, it would be summarized here, but this node focuses on JSON/text outputs related to AI plans and their execution.

Dependencies

  • Requires the Gemini CLI installed and accessible in the system PATH (gemini command).
  • May require an API key credential for Gemini API access, either via input property or environment variable.
  • Optional use of Vertex AI instead of Gemini API.
  • Node uses local filesystem access for reading/writing plans and executing commands.
  • Configurable external MCP servers may require additional setup and credentials.
  • Proper permissions and existence of the specified project directory are necessary.

Troubleshooting

  • Gemini CLI not found or not installed: The node checks for Gemini CLI availability and throws an error if missing. Install it globally using npm (npm install -g @google/gemini-cli).
  • Invalid or inaccessible project path: Errors occur if the specified project directory does not exist, is not a directory, or lacks read/write permissions. Verify the path and permissions.
  • Plan not found or not approved: Execution requires a valid plan ID that corresponds to an existing plan with status "approved". Otherwise, an error is thrown.
  • Timeouts: If Gemini CLI commands take longer than the configured timeout, the process is aborted with a timeout error. Increase the timeout if needed.
  • API key issues: If no API key is provided and none is set in environment variables, authentication may fail.
  • Security risks: Enabling shell commands or auto-approve modes can be dangerous. Use safe mode unless you fully trust the plan contents.
  • Parsing errors: If Gemini CLI returns invalid JSON for plans, the node throws parsing errors. Ensure the AI responses conform to expected formats.

Links and References

This summary covers the "Execute Plan" operation of the Gemini CLI node, focusing on its purpose, configuration, output, dependencies, and common troubleshooting points based on static code analysis.

Discussion