Fix and improve Gemini CLI troubleshooting.md doc (#2734)

Co-authored-by: Sandy Tao <[email protected]>

Author: 8bitmp3

docs/troubleshooting.md

@@ -1,28 +1,38 @@
-# Troubleshooting Guide
+# Troubleshooting guide
 
-This guide provides solutions to common issues and debugging tips.
+This guide provides solutions to common issues and debugging tips, including topics on:
 
-## Authentication
+- Authentication or login errors
+- Frequently asked questions (FAQs)
+- Debugging tips
+- Existing GitHub Issues similar to yours or creating new Issues
+
+## Authentication or login errors
 
 - **Error: `Failed to login. Message: Request contains an invalid argument`**
-  - Users with Google Workspace accounts, or users with Google Cloud accounts
+  - Users with Google Workspace accounts or Google Cloud accounts
     associated with their Gmail accounts may not be able to activate the free
     tier of the Google Code Assist plan.
   - For Google Cloud accounts, you can work around this by setting
     `GOOGLE_CLOUD_PROJECT` to your project ID.
-  - You can also grab an API key from [AI Studio](https://aistudio.google.com/app/apikey), which also includes a
+  - Alternatively, you can obtain the Gemini API key from
+    [Google AI Studio](http://aistudio.google.com/app/apikey), which also includes a
     separate free tier.
 
 ## Frequently asked questions (FAQs)
 
 - **Q: How do I update Gemini CLI to the latest version?**
-  - A: If installed globally via npm, update Gemini CLI using the command `npm install -g @google/gemini-cli@latest`. If run from source, pull the latest changes from the repository and rebuild using `npm run build`.
+  - A: If you installed it globally via `npm`, update it using the command `npm install -g @google/gemini-cli@latest`. If you compiled it from source, pull the latest changes from the repository, and then rebuild using the command `npm run build`.
+
+- **Q: Where are the Gemini CLI configuration or settings files stored?**
+  - A: The Gemini CLI configuration is stored in two `settings.json` files:
+    1. In your home directory: `~/.gemini/settings.json`.
+    2. In your project's root directory: `./.gemini/settings.json`.
 
-- **Q: Where are Gemini CLI configuration files stored?**
-  - A: The CLI configuration is stored within two `settings.json` files: one in your home directory and one in your project's root directory. In both locations, `settings.json` is found in the `.gemini/` folder. Refer to [CLI Configuration](./cli/configuration.md) for more details.
+    Refer to [Gemini CLI Configuration](./cli/configuration.md) for more details.
 
 - **Q: Why don't I see cached token counts in my stats output?**
-  - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Gemini API key or Vertex AI) but not for OAuth users (Google Personal/Enterprise accounts) at this time, as the Code Assist API does not support cached content creation. You can still view your total token usage with the `/stats` command.
+  - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Gemini API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Gemini Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command in Gemini CLI.
 
 ## Common error messages and solutions
 
@@ -31,26 +41,27 @@ This guide provides solutions to common issues and debugging tips.
   - **Solution:**
     Either stop the other process that is using the port or configure the MCP server to use a different port.
 
-- **Error: Command not found (when attempting to run Gemini CLI).**
-  - **Cause:** Gemini CLI is not correctly installed or not in your system's PATH.
+- **Error: Command not found (when attempting to run Gemini CLI with `gemini`).**
+  - **Cause:** Gemini CLI is not correctly installed or it is not in your system's `PATH`.
   - **Solution:**
-    1.  Ensure Gemini CLI installation was successful.
-    2.  If installed globally, check that your npm global binary directory is in your PATH.
-    3.  If running from source, ensure you are using the correct command to invoke it (e.g., `node packages/cli/dist/index.js ...`).
+    The update depends on how you installed Gemini CLI:
+    - If you installed `gemini` globally, check that your `npm` global binary directory is in your `PATH`. You can update Gemini CLI using the command `npm install -g @google/gemini-cli@latest`.
+    - If you are running `gemini` from source, ensure you are using the correct command to invoke it (e.g., `node packages/cli/dist/index.js ...`). To update Gemini CLI, pull the latest changes from the repository, and then rebuild using the command `npm run build`.
 
 - **Error: `MODULE_NOT_FOUND` or import errors.**
   - **Cause:** Dependencies are not installed correctly, or the project hasn't been built.
   - **Solution:**
     1.  Run `npm install` to ensure all dependencies are present.
     2.  Run `npm run build` to compile the project.
+    3.  Verify that the build completed successfully with `npm run start`.
 
 - **Error: "Operation not permitted", "Permission denied", or similar.**
-  - **Cause:** If sandboxing is enabled, then the application is likely attempting an operation restricted by your sandbox, such as writing outside the project directory or system temp directory.
-  - **Solution:** See [Sandboxing](./cli/configuration.md#sandboxing) for more information, including how to customize your sandbox configuration.
+  - **Cause:** When sandboxing is enabled, Gemini CLI may attempt operations that are restricted by your sandbox configuration, such as writing outside the project directory or system temp directory.
+  - **Solution:** Refer to the [Configuration: Sandboxing](./cli/configuration.md#sandboxing) documentation for more information, including how to customize your sandbox configuration.
 
-- **CLI is not interactive in "CI" environments**
-  - **Issue:** The CLI does not enter interactive mode (no prompt appears) if an environment variable starting with `CI_` (e.g., `CI_TOKEN`) is set. This is because the `is-in-ci` package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment.
-  - **Cause:** The `is-in-ci` package checks for the presence of `CI`, `CONTINUOUS_INTEGRATION`, or any environment variable with a `CI_` prefix. When any of these are found, it signals that the environment is non-interactive, which prevents the CLI from starting in its interactive mode.
+- **Gemini CLI is not running in interactive mode in "CI" environments**
+  - **Issue:** The Gemini CLI does not enter interactive mode (no prompt appears) if an environment variable starting with `CI_` (e.g., `CI_TOKEN`) is set. This is because the `is-in-ci` package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment.
+  - **Cause:** The `is-in-ci` package checks for the presence of `CI`, `CONTINUOUS_INTEGRATION`, or any environment variable with a `CI_` prefix. When any of these are found, it signals that the environment is non-interactive, which prevents the Gemini CLI from starting in its interactive mode.
   - **Solution:** If the `CI_` prefixed variable is not needed for the CLI to function, you can temporarily unset it for the command. e.g., `env -u CI_TOKEN gemini`
 
 - **DEBUG mode not working from project .env file**
@@ -72,9 +83,11 @@ This guide provides solutions to common issues and debugging tips.
 - **Tool issues:**
   - If a specific tool is failing, try to isolate the issue by running the simplest possible version of the command or operation the tool performs.
   - For `run_shell_command`, check that the command works directly in your shell first.
-  - For file system tools, double-check paths and permissions.
+  - For _file system tools_, verify that paths are correct and check the permissions.
 
 - **Pre-flight checks:**
   - Always run `npm run preflight` before committing code. This can catch many common issues related to formatting, linting, and type errors.
 
-If you encounter an issue not covered here, consider searching the project's issue tracker on GitHub or reporting a new issue with detailed information.
+## Existing GitHub Issues similar to yours or creating new Issues
+
+If you encounter an issue that was not covered here in this _Troubleshooting guide_, consider searching the Gemini CLI [Issue tracker on GitHub](https://github.com/google-gemini/gemini-cli/issues). If you can't find an issue similar to yours, consider creating a new GitHub Issue with a detailed description. Pull requests are also welcome!