melodic-software/gemini-cli-execution

Gemini CLI Execution

🚨 MANDATORY: Invoke gemini-cli-docs First

STOP - Before executing ANY Gemini CLI command:

1. INVOKE gemini-cli-docs skill
2. QUERY for the specific CLI command syntax (e.g., "headless mode", "piping input")
3. BASE all execution patterns EXCLUSIVELY on official documentation loaded

Overview

This skill provides the operational knowledge to execute the gemini binary effectively within scripts, sub-agents, and automation workflows. It focuses on non-interactive usage.

Command Syntax (v0.18+)

IMPORTANT: Gemini CLI uses positional prompts, not subcommands.

# Correct syntax (positional prompt):
gemini "Your prompt here"

# With options:
gemini "Your prompt" --output-format json -m gemini-2.5-flash

# DEPRECATED (will be removed):
gemini -p "Your prompt"  # -p flag is deprecated

# WRONG (no 'query' subcommand exists):
gemini query "Your prompt"  # This does NOT work

When to Use This Skill

Keywords: run gemini, execute gemini, gemini cli command, headless gemini, pipe to gemini, automated planning, gemini prompt, interactive shell

Use this skill when:

• Invoking Gemini CLI from an agent (e.g., gemini-planner)
• Running one-off queries: gemini "prompt"
• Piping context: cat file.js | gemini "refactor this"
• Using Interactive Shell for tools like vim or top
• Scripting complex workflows involving Gemini

Execution Patterns

1. Single Shot Query (Non-Interactive)

Use positional prompt for direct queries:

gemini "Create a plan for a React app"

# With JSON output for parsing:
gemini "Create a plan for a React app" --output-format json

2. Piping Context

Pass file content or logs via stdin:

cat logs.txt | gemini "Analyze these error logs"

# With model selection:
cat src/*.ts | gemini "Review this code" -m gemini-2.5-flash

3. JSON Output for Automation

Always use --output-format json for scripting:

result=$(gemini "What is 2+2?" --output-format json)
response=$(echo "$result" | jq -r '.response')
tokens=$(echo "$result" | jq '.stats.models | to_entries | map(.value.tokens.total) | add')

4. Sandbox Execution

Run commands in isolated environment:

gemini -s "Run: npm install untrusted-package" --yolo --output-format json

5. Interactive Shell Mode

Enable interactive shell for commands requiring user input (e.g., vim, git rebase).

• Enable: Set tools.shell.enableInteractiveShell: true in settings.json.
• Usage: gemini "run vim file.txt" (User must handle input).

Key CLI Flags

| Flag | Description | | --- | --- | | --output-format json | Return structured JSON (essential for automation) | | -m, --model | Select model (gemini-2.5-flash, gemini-2.5-pro) | | -s, --sandbox | Run in sandbox isolation | | -y, --yolo | Auto-approve all tool calls | | -r, --resume | Resume previous session | | -i, --prompt-interactive | Start interactive mode after prompt |

Keyword Registry (Delegates to gemini-cli-docs)

| Topic | Query Keywords | | :--- | :--- | | Basic Query | cli prompt syntax, positional prompt | | Headless/Scripting | headless mode, non-interactive, scripting gemini | | Output Formatting | json output, output-format, stream-json | | Sandbox | sandbox, -s flag, docker sandbox | | Interactive Shell | interactive shell tool, enableInteractiveShell, interactive commands |

Quick Decision Tree

What do you want to do?

1. Ask a Question -> gemini "Question"
2. Analyze a File -> cat file | gemini "Analyze"
3. Generate a Plan -> gemini "Plan for X"
4. Run Interactive Tool -> gemini "run vim file.txt" (with enableInteractiveShell)
5. Parse Results -> Add --output-format json and use jq

Troubleshooting

Issue: CLI hangs or waits for input. Fix: Ensure you are NOT using the interactive chat mode. Use positional prompt for one-shot queries.

Issue: Command not found: gemini query Fix: There is no query subcommand. Use positional prompt: gemini "your prompt"

Issue: Warning about deprecated -p flag Fix: Use positional syntax instead: gemini "prompt" not gemini -p "prompt"

Test Scenarios

Scenario 1: Single Shot Query

Query: "Run a Gemini query to analyze this code" Expected Behavior:

• Skill activates on "run gemini" keyword
• Delegates to gemini-cli-docs for command syntax
• Returns proper positional prompt syntax Success Criteria: User receives correct gemini "prompt" syntax

Scenario 2: Piped Input

Query: "How do I send file contents to Gemini CLI?" Expected Behavior:

• Skill activates on "pipe to gemini"
• Provides cat file | gemini "prompt" pattern Success Criteria: User receives working piping example

Scenario 3: JSON Output Parsing

Query: "How do I get JSON output from Gemini for automation?" Expected Behavior:

• Skill activates on "automated" or "json output"
• Returns --output-format json flag usage Success Criteria: User receives parseable JSON output pattern

References

Official Documentation: Query gemini-cli-docs for:

• "cli commands"
• "headless usage"
• "output format"

Version History

• v1.1.0 (2025-12-01): Added Test Scenarios section
• v1.0.0 (2025-11-25): Initial release