@dgxo/mashadevcli 1.1.0

package/bundle/docs/get-started/authentication.md

@@ -0,0 +1,402 @@
+# Gemini CLI authentication setup
+
+To use Gemini CLI, you'll need to authenticate with Google. This guide helps you
+quickly find the best way to sign in based on your account type and how you're
+using the CLI.
+
+For most users, we recommend starting Gemini CLI and logging in with your
+personal Google account.
+
+## Choose your authentication method <a id="auth-methods"></a>
+
+Select the authentication method that matches your situation in the table below:
+
+| User Type / Scenario                                                   | Recommended Authentication Method                                | Google Cloud Project Required                               |
+| :--------------------------------------------------------------------- | :--------------------------------------------------------------- | :---------------------------------------------------------- |
+| Individual Google accounts                                             | [Login with Google](#login-google)                               | No, with exceptions                                         |
+| Organization users with a company, school, or Google Workspace account | [Login with Google](#login-google)                               | [Yes](#set-gcp)                                             |
+| AI Studio user with a Gemini API key                                   | [Use Gemini API Key](#gemini-api)                                | No                                                          |
+| Google Cloud Vertex AI user                                            | [Vertex AI](#vertex-ai)                                          | [Yes](#set-gcp)                                             |
+| [Headless mode](#headless)                                             | [Use Gemini API Key](#gemini-api) or<br> [Vertex AI](#vertex-ai) | No (for Gemini API Key)<br> [Yes](#set-gcp) (for Vertex AI) |
+
+### What is my Google account type?
+
+- **Individual Google accounts:** Includes all
+  [free tier accounts](../resources/quota-and-pricing.md#free-usage) such as
+  Gemini Code Assist for individuals, as well as paid subscriptions for
+  [Google AI Pro and Ultra](https://gemini.google/subscriptions/).
+
+- **Organization accounts:** Accounts using paid licenses through an
+  organization such as a company, school, or
+  [Google Workspace](https://workspace.google.com/). Includes
+  [Google AI Ultra for Business](https://support.google.com/a/answer/16345165)
+  subscriptions.
+
+## (Recommended) Login with Google <a id="login-google"></a>
+
+If you run Gemini CLI on your local machine, the simplest authentication method
+is logging in with your Google account. This method requires a web browser on a
+machine that can communicate with the terminal running Gemini CLI (e.g., your
+local machine).
+
+> **Important:** If you are a **Google AI Pro** or **Google AI Ultra**
+> subscriber, use the Google account associated with your subscription.
+
+To authenticate and use Gemini CLI:
+
+1. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+2. Select **Login with Google**. Gemini CLI opens a login prompt using your web
+   browser. Follow the on-screen instructions. Your credentials will be cached
+   locally for future sessions.
+
+### Do I need to set my Google Cloud project?
+
+Most individual Google accounts (free and paid) don't require a Google Cloud
+project for authentication. However, you'll need to set a Google Cloud project
+when you meet at least one of the following conditions:
+
+- You are using a company, school, or Google Workspace account.
+- You are using a Gemini Code Assist license from the Google Developer Program.
+- You are using a license from a Gemini Code Assist subscription.
+
+For instructions, see [Set your Google Cloud Project](#set-gcp).
+
+## Use Gemini API key <a id="gemini-api"></a>
+
+If you don't want to authenticate using your Google account, you can use an API
+key from Google AI Studio.
+
+To authenticate and use Gemini CLI with a Gemini API key:
+
+1. Obtain your API key from
+   [Google AI Studio](https://aistudio.google.com/app/apikey).
+
+2. Set the `GEMINI_API_KEY` environment variable to your key. For example:
+
+   **macOS/Linux**
+
+   ```bash
+   # Replace YOUR_GEMINI_API_KEY with the key from AI Studio
+   export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
+   ```
+
+   **Windows (PowerShell)**
+
+   ```powershell
+   # Replace YOUR_GEMINI_API_KEY with the key from AI Studio
+   $env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
+   ```
+
+   To make this setting persistent, see
+   [Persisting Environment Variables](#persisting-vars).
+
+3. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+4. Select **Use Gemini API key**.
+
+> **Warning:** Treat API keys, especially for services like Gemini, as sensitive
+> credentials. Protect them to prevent unauthorized access and potential misuse
+> of the service under your account.
+
+## Use Vertex AI <a id="vertex-ai"></a>
+
+To use Gemini CLI with Google Cloud's Vertex AI platform, choose from the
+following authentication options:
+
+- A. Application Default Credentials (ADC) using `gcloud`.
+- B. Service account JSON key.
+- C. Google Cloud API key.
+
+Regardless of your authentication method for Vertex AI, you'll need to set
+`GOOGLE_CLOUD_PROJECT` to your Google Cloud project ID with the Vertex AI API
+enabled, and `GOOGLE_CLOUD_LOCATION` to the location of your Vertex AI resources
+or the location where you want to run your jobs.
+
+For example:
+
+**macOS/Linux**
+
+```bash
+# Replace with your project ID and desired location (e.g., us-central1)
+export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
+```
+
+**Windows (PowerShell)**
+
+```powershell
+# Replace with your project ID and desired location (e.g., us-central1)
+$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+$env:GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
+```
+
+To make any Vertex AI environment variable settings persistent, see
+[Persisting Environment Variables](#persisting-vars).
+
+#### A. Vertex AI - application default credentials (ADC) using `gcloud`
+
+Consider this authentication method if you have Google Cloud CLI installed.
+
+> **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you
+> must unset them to use ADC:
+>
+> **macOS/Linux**
+>
+> ```bash
+> unset GOOGLE_API_KEY GEMINI_API_KEY
+> ```
+>
+> **Windows (PowerShell)**
+>
+> ```powershell
+> Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore
+> ```
+
+1. Verify you have a Google Cloud project and Vertex AI API is enabled.
+
+2. Log in to Google Cloud:
+
+   ```bash
+   gcloud auth application-default login
+   ```
+
+3. [Configure your Google Cloud Project](#set-gcp).
+
+4. Start the CLI:
+
+   ```bash
+   gemini
+   ```
+
+5. Select **Vertex AI**.
+
+#### B. Vertex AI - service account JSON key
+
+Consider this method of authentication in non-interactive environments, CI/CD
+pipelines, or if your organization restricts user-based ADC or API key creation.
+
+> **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you
+> must unset them:
+>
+> **macOS/Linux**
+>
+> ```bash
+> unset GOOGLE_API_KEY GEMINI_API_KEY
+> ```
+>
+> **Windows (PowerShell)**
+>
+> ```powershell
+> Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore
+> ```
+
+1.  [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete)
+    and download the provided JSON file. Assign the "Vertex AI User" role to the
+    service account.
+
+2.  Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON
+    file's absolute path. For example:
+
+    **macOS/Linux**
+
+    ```bash
+    # Replace /path/to/your/keyfile.json with the actual path
+    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    # Replace C:\path\to\your\keyfile.json with the actual path
+    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\keyfile.json"
+    ```
+
+3.  [Configure your Google Cloud Project](#set-gcp).
+
+4.  Start the CLI:
+
+    ```bash
+    gemini
+    ```
+
+5.  Select **Vertex AI**.
+    > **Warning:** Protect your service account key file as it gives access to
+    > your resources.
+
+#### C. Vertex AI - Google Cloud API key
+
+1.  Obtain a Google Cloud API key:
+    [Get an API Key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser).
+
+2.  Set the `GOOGLE_API_KEY` environment variable:
+
+    **macOS/Linux**
+
+    ```bash
+    # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
+    export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key
+    $env:GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
+    ```
+
+    > **Note:** If you see errors like
+    > `"API keys are not supported by this API..."`, your organization might
+    > restrict API key usage for this service. Try the other Vertex AI
+    > authentication methods instead.
+
+3.  [Configure your Google Cloud Project](#set-gcp).
+
+4.  Start the CLI:
+
+    ```bash
+    gemini
+    ```
+
+5.  Select **Vertex AI**.
+
+## Set your Google Cloud project <a id="set-gcp"></a>
+
+> **Important:** Most individual Google accounts (free and paid) don't require a
+> Google Cloud project for authentication.
+
+When you sign in using your Google account, you may need to configure a Google
+Cloud project for Gemini CLI to use. This applies when you meet at least one of
+the following conditions:
+
+- You are using a Company, School, or Google Workspace account.
+- You are using a Gemini Code Assist license from the Google Developer Program.
+- You are using a license from a Gemini Code Assist subscription.
+
+To configure Gemini CLI to use a Google Cloud project, do the following:
+
+1.  [Find your Google Cloud Project ID](https://support.google.com/googleapi/answer/7014113).
+
+2.  [Enable the Gemini for Cloud API](https://cloud.google.com/gemini/docs/discover/set-up-gemini#enable-api).
+
+3.  [Configure necessary IAM access permissions](https://cloud.google.com/gemini/docs/discover/set-up-gemini#grant-iam).
+
+4.  Configure your environment variables. Set either the `GOOGLE_CLOUD_PROJECT`
+    or `GOOGLE_CLOUD_PROJECT_ID` variable to the project ID to use with Gemini
+    CLI. Gemini CLI checks for `GOOGLE_CLOUD_PROJECT` first, then falls back to
+    `GOOGLE_CLOUD_PROJECT_ID`.
+
+    For example, to set the `GOOGLE_CLOUD_PROJECT_ID` variable:
+
+    **macOS/Linux**
+
+    ```bash
+    # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
+    export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID
+    $env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
+    ```
+
+    To make this setting persistent, see
+    [Persisting Environment Variables](#persisting-vars).
+
+## Persisting environment variables <a id="persisting-vars"></a>
+
+To avoid setting environment variables for every terminal session, you can
+persist them with the following methods:
+
+1.  **Add your environment variables to your shell configuration file:** Append
+    the environment variable commands to your shell's startup file.
+
+    **macOS/Linux** (e.g., `~/.bashrc`, `~/.zshrc`, or `~/.profile`):
+
+    ```bash
+    echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
+    source ~/.bashrc
+    ```
+
+    **Windows (PowerShell)** (e.g., `$PROFILE`):
+
+    ```powershell
+    Add-Content -Path $PROFILE -Value '$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"'
+    . $PROFILE
+    ```
+
+    > **Warning:** Be aware that when you export API keys or service account
+    > paths in your shell configuration file, any process launched from that
+    > shell can read them.
+
+2.  **Use a `.env` file:** Create a `.gemini/.env` file in your project
+    directory or home directory. Gemini CLI automatically loads variables from
+    the first `.env` file it finds, searching up from the current directory,
+    then in your home directory's `.gemini/.env` (e.g., `~/.gemini/.env` or
+    `%USERPROFILE%\.gemini\.env`).
+
+    Example for user-wide settings:
+
+    **macOS/Linux**
+
+    ```bash
+    mkdir -p ~/.gemini
+    cat >> ~/.gemini/.env <<'EOF'
+    GOOGLE_CLOUD_PROJECT="your-project-id"
+    # Add other variables like GEMINI_API_KEY as needed
+    EOF
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini"
+    @"
+    GOOGLE_CLOUD_PROJECT="your-project-id"
+    # Add other variables like GEMINI_API_KEY as needed
+    "@ | Out-File -FilePath "$env:USERPROFILE\.gemini\.env" -Encoding utf8 -Append
+    ```
+
+Variables are loaded from the first file found, not merged.
+
+## Running in Google Cloud environments <a id="cloud-env"></a>
+
+When running Gemini CLI within certain Google Cloud environments, authentication
+is automatic.
+
+In a Google Cloud Shell environment, Gemini CLI typically authenticates
+automatically using your Cloud Shell credentials. In Compute Engine
+environments, Gemini CLI automatically uses Application Default Credentials
+(ADC) from the environment's metadata server.
+
+If automatic authentication fails, use one of the interactive methods described
+on this page.
+
+## Running in headless mode <a id="headless"></a>
+
+[Headless mode](../cli/headless) will use your existing authentication method,
+if an existing authentication credential is cached.
+
+If you have not already logged in with an authentication credential, you must
+configure authentication using environment variables:
+
+- [Use Gemini API Key](#gemini-api)
+- [Vertex AI](#vertex-ai)
+
+## What's next?
+
+Your authentication method affects your quotas, pricing, Terms of Service, and
+privacy notices. Review the following pages to learn more:
+
+- [Gemini CLI: Quotas and Pricing](../resources/quota-and-pricing.md).
+- [Gemini CLI: Terms of Service and Privacy Notice](../resources/tos-privacy.md).

package/bundle/docs/get-started/examples.md

@@ -0,0 +1,139 @@
+# Gemini CLI examples
+
+Gemini CLI helps you automate common engineering tasks by combining AI reasoning
+with local system tools. This document provides examples of how to use the CLI
+for file management, code analysis, and data transformation.
+
+> **Note:** These examples demonstrate potential capabilities. Your actual
+> results can vary based on the model used and your project environment.
+
+## Rename your photographs based on content
+
+You can use Gemini CLI to automate file management tasks that require visual
+analysis. In this example, Gemini CLI renames images based on their actual
+subject matter.
+
+Scenario: You have a folder containing the following files:
+
+```bash
+photos/photo1.png
+photos/photo2.png
+photos/photo3.png
+```
+
+Give Gemini the following prompt:
+
+```cli
+Rename the photos in my "photos" directory based on their contents.
+```
+
+Result: Gemini asks for permission to rename your files.
+
+Select **Allow once** and your files are renamed:
+
+```bash
+photos/yellow_flowers.png
+photos/antique_dresser.png
+photos/green_android_robot.png
+```
+
+## Explain a repository by reading its code
+
+Gemini CLI is effective for rapid codebase exploration. The following example
+shows how to ask Gemini CLI to fetch, analyze, and summarize a remote project.
+
+Scenario: You want to understand how a popular open-source utility works by
+inspecting its code, not just its README.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works.
+```
+
+Result: Gemini performs a sequence of actions to answer your request.
+
+1.  First, it asks for permission to run `git clone` to download the repository.
+2.  Next, it finds the important source files and asks for permission to read
+    them.
+3.  Finally, after analyzing the code, it provides a summary.
+
+Gemini CLI returns an explanation based on the actual source code:
+
+```markdown
+The `chalk` library is a popular npm package for styling terminal output with
+colors. After analyzing the source code, here's how it works:
+
+- **Core functionality:** The main file sets up a chainable API. Each color or
+  modifier (like `bold` or `italic`) is a getter that appends the corresponding
+  ANSI escape code to an internal stack.
+
+- **Chainable API:** When you call `chalk.red.bold('Hello')`, you are accessing
+  getters. The `red` getter adds the red color code, and the `bold` getter adds
+  the bold code.
+
+- **Output generation:** When the chain is treated as a string (e.g., in
+  `console.log`), a final `toString()` method is called. This method joins all
+  the stored ANSI codes, wraps them around the input string ('Hello'), and adds
+  a reset code at the end. This produces the final, styled string that the
+  terminal can render.
+```
+
+## Combine two spreadsheets into one spreadsheet
+
+Gemini CLI can process and transform data across multiple files. Use this
+capability to merge reports or reformat data sets without manual copying.
+
+Scenario: You have two .csv files: `Revenue - 2023.csv` and
+`Revenue - 2024.csv`. Each file contains monthly revenue figures.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Combine the two .csv files into a single .csv file, with each year a different column.
+```
+
+Result: Gemini CLI reads each file and then asks for permission to write a new
+file. Provide your permission and Gemini CLI provides the combined data:
+
+```csv
+Month,2023,2024
+January,0,1000
+February,0,1200
+March,0,2400
+April,900,500
+May,1000,800
+June,1000,900
+July,1200,1000
+August,1800,400
+September,2000,2000
+October,2400,3400
+November,3400,1800
+December,2100,9000
+```
+
+## Run unit tests
+
+Gemini CLI can generate boilerplate code and tests based on your existing
+implementation. This example demonstrates how to request code coverage for a
+JavaScript component.
+
+Scenario: You've written a simple login page. You wish to write unit tests to
+ensure that your login page has code coverage.
+
+Give Gemini CLI the following prompt:
+
+```cli
+Write unit tests for Login.js.
+```
+
+Result: Gemini CLI asks for permission to write a new file and creates a test
+for your login page.
+
+## Next steps
+
+- Follow the [File management](../cli/tutorials/file-management.md) guide to
+  start working with your codebase.
+- Follow the [Quickstart](./index.md) to start your first session.
+- See the [Cheatsheet](../cli/cli-reference.md) for a quick reference of
+  available commands.

package/bundle/docs/get-started/gemini-3.md

@@ -0,0 +1,115 @@
+# Gemini 3 Pro and Gemini 3 Flash on Gemini CLI
+
+Gemini 3 Pro and Gemini 3 Flash are available on Gemini CLI for all users!
+
+> **Note:** Gemini 3.1 Pro Preview is rolling out. To determine whether you have
+> access to Gemini 3.1, use the `/model` command and select **Manual**. If you
+> have access, you will see `gemini-3.1-pro-preview`.
+>
+> If you have access to Gemini 3.1, it will be included in model routing when
+> you select **Auto (Gemini 3)**. You can also launch the Gemini 3.1 model
+> directly using the `-m` flag:
+>
+> ```
+> gemini -m gemini-3.1-pro-preview
+> ```
+>
+> Learn more about [models](../cli/model.md) and
+> [model routing](../cli/model-routing.md).
+
+## How to get started with Gemini 3 on Gemini CLI
+
+Get started by upgrading Gemini CLI to the latest version:
+
+```bash
+npm install -g @dgxo/mashadevcli@latest
+```
+
+After you’ve confirmed your version is 0.21.1 or later:
+
+1. Run `/model`.
+2. Select **Auto (Gemini 3)**.
+
+For more information, see [Gemini CLI model selection](../cli/model.md).
+
+### Usage limits and fallback
+
+Gemini CLI will tell you when you reach your Gemini 3 Pro daily usage limit.
+When you encounter that limit, you’ll be given the option to switch to Gemini
+2.5 Pro, upgrade for higher limits, or stop. You’ll also be told when your usage
+limit resets and Gemini 3 Pro can be used again.
+
+Similarly, when you reach your daily usage limit for Gemini 2.5 Pro, you’ll see
+a message prompting fallback to Gemini 2.5 Flash.
+
+### Capacity errors
+
+There may be times when the Gemini 3 Pro model is overloaded. When that happens,
+Gemini CLI will ask you to decide whether you want to keep trying Gemini 3 Pro
+or fallback to Gemini 2.5 Pro.
+
+> **Note:** The **Keep trying** option uses exponential backoff, in which Gemini
+> CLI waits longer between each retry, when the system is busy. If the retry
+> doesn't happen immediately, please wait a few minutes for the request to
+> process.
+
+### Model selection and routing types
+
+When using Gemini CLI, you may want to control how your requests are routed
+between models. By default, Gemini CLI uses **Auto** routing.
+
+When using Gemini 3 Pro, you may want to use Auto routing or Pro routing to
+manage your usage limits:
+
+- **Auto routing:** Auto routing first determines whether a prompt involves a
+  complex or simple operation. For simple prompts, it will automatically use
+  Gemini 2.5 Flash. For complex prompts, if Gemini 3 Pro is enabled, it will use
+  Gemini 3 Pro; otherwise, it will use Gemini 2.5 Pro.
+- **Pro routing:** If you want to ensure your task is processed by the most
+  capable model, use `/model` and select **Pro**. Gemini CLI will prioritize the
+  most capable model available, including Gemini 3 Pro if it has been enabled.
+
+To learn more about selecting a model and routing, refer to
+[Gemini CLI Model Selection](../cli/model.md).
+
+## How to enable Gemini 3 with Gemini CLI on Gemini Code Assist
+
+If you're using Gemini Code Assist Standard or Gemini Code Assist Enterprise,
+enabling Gemini 3 Pro on Gemini CLI requires configuring your release channels.
+Using Gemini 3 Pro will require two steps: administrative enablement and user
+enablement.
+
+To learn more about these settings, refer to
+[Configure Gemini Code Assist release channels](https://developers.google.com/gemini-code-assist/docs/configure-release-channels).
+
+### Administrator instructions
+
+An administrator with **Google Cloud Settings Admin** permissions must follow
+these directions:
+
+- Navigate to the Google Cloud Project you're using with Gemini CLI for Code
+  Assist.
+- Go to **Admin for Gemini** > **Settings**.
+- Under **Release channels for Gemini Code Assist in local IDEs** select
+  **Preview**.
+- Click **Save changes**.
+
+### User instructions
+
+Wait for two to three minutes after your administrator has enabled **Preview**,
+then:
+
+- Open Gemini CLI.
+- Use the `/settings` command.
+- Set **Preview Features** to `true`.
+
+Restart Gemini CLI and you should have access to Gemini 3.
+
+## Need help?
+
+If you need help, we recommend searching for an existing
+[GitHub issue](https://github.com/DGameGT/mashadev-cli/issues). If you
+cannot find a GitHub issue that matches your concern, you can
+[create a new issue](https://github.com/DGameGT/mashadev-cli/issues/new/choose).
+For comments and feedback, consider opening a
+[GitHub discussion](https://github.com/DGameGT/mashadev-cli/discussions).