fix(docs): fix headless mode docs

[ame2en]

Summary

This PR corrects inaccuracies in the documentation regarding headless mode. It ensures that the examples and command-line references correctly reflect that positional arguments run interactively by default in a TTY environment, and that the -p or --prompt flag is explicitly required for non-interactive (headless) execution in those cases.

Details

The fix involves the following changes:

• Automation Tutorials: Updated descriptions in docs/cli/tutorials/automation.md to properly use the -p flag in TTY examples, while maintaining that piped or redirected commands automatically trigger headless mode.
• CLI Reference: Corrected the command tables in docs/cli/cli-reference.md to clarify the difference between gemini "query" and gemini -p "query". Removed the deprecation notice from the -p/--prompt option description.
• Headless Mode Reference: Updated the technical description in docs/cli/headless.md to indicate that headless mode is triggered by a non-TTY environment or by explicitly passing the -p/--prompt flag.

Related Issues

Closes #21111

How to Validate locally

1. Run a positional argument command in a standard terminal (TTY): npm run start -- "tell me a joke"
2. Verify the agent spins up interactively and stays open.
3. Run the same query explicitly with the prompt flag: npm run start -- -p "tell me a joke"
4. Verify the agent process prints the response and successfully exits (headless mode).
5. Verify that piping also still behaves headlessly without -p: echo "tell me a joke" | npm run start

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses inaccuracies in the documentation for the Gemini CLI's headless mode. It clarifies that positional arguments run interactively by default in TTY environments, and the -p or --prompt flag is now explicitly required for non-interactive execution in such cases. The changes ensure consistency across various documentation sections, providing clearer guidance for users on how to properly invoke headless mode.

Highlights

• Headless Mode Clarification: Updated documentation to explicitly state that headless mode is triggered by a non-TTY environment or by using the -p/--prompt flag, rather than solely by positional arguments.
• Automation Tutorial Examples: Modified code examples in automation tutorials to correctly demonstrate the use of the -p flag for non-interactive commands, ensuring accurate guidance for users.
• CLI Reference Updates: Revised the CLI command tables to differentiate between interactive and non-interactive positional arguments and removed the deprecation notice from the -p/--prompt option, clarifying its current role.
• Changelog Corrections: Updated existing changelog entries to reflect the correct usage of the -p flag for non-interactive commands, maintaining consistency across documentation.

Changelog

• docs/changelogs/index.md
  • Updated example command for "Non-interactive MCP commands" to include -p.
  • Updated example command for "Custom commands in Headless Mode" to include -p.
• docs/cli/cli-reference.md
  • Modified the "CLI commands" table to correctly list gemini -p "query" for non-interactive queries and gemini "query" for interactive queries.
  • Added a new description for positional arguments clarifying default interactive mode in TTY and the need for -p for non-interactive execution.
  • Removed the "Deprecated" notice from the --prompt (-p) flag description and clarified its function to force non-interactive mode.
• docs/cli/headless.md
  • Updated the "Technical reference" to state that headless mode is triggered by a non-TTY environment or by providing a query with the -p (or --prompt) flag.
• docs/cli/tutorials/automation.md
  • Updated the introductory text on how to use headless mode, emphasizing the -p flag.
  • Modified all example commands (gemini "query", cat | gemini "query", git diff | gemini "query", script examples) to explicitly include the -p flag for headless execution.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request aims to correct the documentation for headless mode. All review comments provided are valid and align with the rule to maintain consistency and accuracy in documentation. Specifically, a duplicate line in the CLI reference needs removal, and several examples in the automation tutorial incorrectly include the -p flag where headless mode is automatically enabled by piping or redirection. The suggestions provided will help clarify these inaccuracies.

_{Note: Security Review has been skipped due to the limited scope of the PR.}

[g-samroberts]

Hi @ame2en, please make the requested changes. Ignore the bot comments, I've resolved them, because I think when both positional or a flag works (like when piping) it's better use the flag in the example to remain unambiguous.

[ame2en]

@g-samroberts solved the review comments, let me know if any other changes are required