@dgxo/mashadevcli 1.1.0

package/bundle/docs/cli/themes.md

@@ -0,0 +1,269 @@
+# Themes
+
+Gemini CLI supports a variety of themes to customize its color scheme and
+appearance. You can change the theme to suit your preferences via the `/theme`
+command or `"theme":` configuration setting.
+
+## Available themes
+
+Gemini CLI comes with a selection of pre-defined themes, which you can list
+using the `/theme` command within Gemini CLI:
+
+- **Dark themes:**
+  - `ANSI`
+  - `Atom One`
+  - `Ayu`
+  - `Default`
+  - `Dracula`
+  - `GitHub`
+  - `Solarized Dark`
+- **Light themes:**
+  - `ANSI Light`
+  - `Ayu Light`
+  - `Default Light`
+  - `GitHub Light`
+  - `Google Code`
+  - `Solarized Light`
+  - `Xcode`
+
+### Changing themes
+
+1.  Enter `/theme` into Gemini CLI.
+2.  A dialog or selection prompt appears, listing the available themes.
+3.  Using the arrow keys, select a theme. Some interfaces might offer a live
+    preview or highlight as you select.
+4.  Confirm your selection to apply the theme.
+
+**Note:** If a theme is defined in your `settings.json` file (either by name or
+by a file path), you must remove the `"theme"` setting from the file before you
+can change the theme using the `/theme` command.
+
+### Theme persistence
+
+Selected themes are saved in Gemini CLI's
+[configuration](../reference/configuration.md) so your preference is remembered
+across sessions.
+
+---
+
+## Custom color themes
+
+Gemini CLI lets you create your own custom color themes by specifying them in
+your `settings.json` file. This gives you full control over the color palette
+used in the CLI.
+
+### How to define a custom theme
+
+Add a `customThemes` block to your user, project, or system `settings.json`
+file. Each custom theme is defined as an object with a unique name and a set of
+nested configuration objects. For example:
+
+```json
+{
+  "ui": {
+    "customThemes": {
+      "MyCustomTheme": {
+        "name": "MyCustomTheme",
+        "type": "custom",
+        "background": {
+          "primary": "#181818"
+        },
+        "text": {
+          "primary": "#f0f0f0",
+          "secondary": "#a0a0a0"
+        }
+      }
+    }
+  }
+}
+```
+
+**Configuration objects:**
+
+- **`text`**: Defines text colors.
+  - `primary`: The default text color.
+  - `secondary`: Used for less prominent text.
+  - `link`: Color for URLs and links.
+  - `accent`: Used for highlights and emphasis.
+  - `response`: Precedence over `primary` for rendering model responses.
+- **`background`**: Defines background colors.
+  - `primary`: The main background color of the UI.
+  - `diff.added`: Background for added lines in diffs.
+  - `diff.removed`: Background for removed lines in diffs.
+- **`border`**: Defines border colors.
+  - `default`: The standard border color.
+  - `focused`: Border color when an element is focused.
+- **`status`**: Colors for status indicators.
+  - `success`: Used for successful operations.
+  - `warning`: Used for warnings.
+  - `error`: Used for errors.
+- **`ui`**: Other UI elements.
+  - `comment`: Color for code comments.
+  - `symbol`: Color for code symbols and operators.
+  - `gradient`: An array of colors used for gradient effects.
+
+**Required properties:**
+
+- `name` (must match the key in the `customThemes` object and be a string)
+- `type` (must be the string `"custom"`)
+
+While all sub-properties are technically optional, we recommend providing at
+least `background.primary`, `text.primary`, `text.secondary`, and the various
+accent colors via `text.link`, `text.accent`, and `status` to ensure a cohesive
+UI.
+
+You can use either hex codes (e.g., `#FF0000`) **or** standard CSS color names
+(e.g., `coral`, `teal`, `blue`) for any color value. See
+[CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords)
+for a full list of supported names.
+
+You can define multiple custom themes by adding more entries to the
+`customThemes` object.
+
+### Loading themes from a file
+
+In addition to defining custom themes in `settings.json`, you can also load a
+theme directly from a JSON file by specifying the file path in your
+`settings.json`. This is useful for sharing themes or keeping them separate from
+your main configuration.
+
+To load a theme from a file, set the `theme` property in your `settings.json` to
+the path of your theme file:
+
+```json
+{
+  "ui": {
+    "theme": "/path/to/your/theme.json"
+  }
+}
+```
+
+The theme file must be a valid JSON file that follows the same structure as a
+custom theme defined in `settings.json`.
+
+**Example `my-theme.json`:**
+
+```json
+{
+  "name": "Gruvbox Dark",
+  "type": "custom",
+  "background": {
+    "primary": "#282828",
+    "diff": {
+      "added": "#2b3312",
+      "removed": "#341212"
+    }
+  },
+  "text": {
+    "primary": "#ebdbb2",
+    "secondary": "#a89984",
+    "link": "#83a598",
+    "accent": "#d3869b"
+  },
+  "border": {
+    "default": "#3c3836",
+    "focused": "#458588"
+  },
+  "status": {
+    "success": "#b8bb26",
+    "warning": "#fabd2f",
+    "error": "#fb4934"
+  },
+  "ui": {
+    "comment": "#928374",
+    "symbol": "#8ec07c",
+    "gradient": ["#cc241d", "#d65d0e", "#d79921"]
+  }
+}
+```
+
+**Security note:** For your safety, Gemini CLI will only load theme files that
+are located within your home directory. If you attempt to load a theme from
+outside your home directory, a warning will be displayed and the theme will not
+be loaded. This is to prevent loading potentially malicious theme files from
+untrusted sources.
+
+### Example custom theme
+
+<img src="../assets/theme-custom.png" alt="Custom theme example" width="600" />
+
+### Using your custom theme
+
+- Select your custom theme using the `/theme` command in Gemini CLI. Your custom
+  theme will appear in the theme selection dialog.
+- Or, set it as the default by adding `"theme": "MyCustomTheme"` to the `ui`
+  object in your `settings.json`.
+- Custom themes can be set at the user, project, or system level, and follow the
+  same [configuration precedence](../reference/configuration.md) as other
+  settings.
+
+### Themes from extensions
+
+[Extensions](../extensions/reference.md#themes) can also provide custom themes.
+Once an extension is installed and enabled, its themes are automatically added
+to the selection list in the `/theme` command.
+
+Themes from extensions appear with the extension name in parentheses to help you
+identify their source, for example: `shades-of-green (green-extension)`.
+
+---
+
+## Dark themes
+
+### ANSI
+
+<img src="/assets/theme-ansi.png" alt="ANSI theme" width="600" />
+
+### Atom OneDark
+
+<img src="/assets/theme-atom-one.png" alt="Atom One theme" width="600">
+
+### Ayu
+
+<img src="/assets/theme-ayu.png" alt="Ayu theme" width="600">
+
+### Default
+
+<img src="/assets/theme-default.png" alt="Default theme" width="600">
+
+### Dracula
+
+<img src="/assets/theme-dracula.png" alt="Dracula theme" width="600">
+
+### GitHub
+
+<img src="/assets/theme-github.png" alt="GitHub theme" width="600">
+
+### Solarized Dark
+
+<img src="/assets/theme-solarized-dark.png" alt="Solarized Dark theme" width="600">
+
+## Light themes
+
+### ANSI Light
+
+<img src="/assets/theme-ansi-light.png" alt="ANSI Light theme" width="600">
+
+### Ayu Light
+
+<img src="/assets/theme-ayu-light.png" alt="Ayu Light theme" width="600">
+
+### Default Light
+
+<img src="/assets/theme-default-light.png" alt="Default Light theme" width="600">
+
+### GitHub Light
+
+<img src="/assets/theme-github-light.png" alt="GitHub Light theme" width="600">
+
+### Google Code
+
+<img src="/assets/theme-google-light.png" alt="Google Code theme" width="600">
+
+### Solarized Light
+
+<img src="/assets/theme-solarized-light.png" alt="Solarized Light theme" width="600">
+
+### Xcode
+
+<img src="/assets/theme-xcode-light.png" alt="Xcode Light theme" width="600">

package/bundle/docs/cli/token-caching.md

@@ -0,0 +1,20 @@
+# Token caching and cost optimization
+
+Gemini CLI automatically optimizes API costs through token caching when using
+API key authentication (Gemini API key or Vertex AI). This feature reuses
+previous system instructions and context to reduce the number of tokens
+processed in subsequent requests.
+
+**Token caching is available for:**
+
+- API key users (Gemini API key)
+- Vertex AI users (with project and location setup)
+
+**Token caching is not available for:**
+
+- OAuth users (Google Personal/Enterprise accounts) - the Code Assist API does
+  not support cached content creation at this time
+
+You can view your token usage and cached token savings using the `/stats`
+command. When cached tokens are available, they will be displayed in the stats
+output.

package/bundle/docs/cli/trusted-folders.md

@@ -0,0 +1,126 @@
+# Trusted Folders
+
+The Trusted Folders feature is a security setting that gives you control over
+which projects can use the full capabilities of the Gemini CLI. It prevents
+potentially malicious code from running by asking you to approve a folder before
+the CLI loads any project-specific configurations from it.
+
+## Enabling the feature
+
+The Trusted Folders feature is **disabled by default**. To use it, you must
+first enable it in your settings.
+
+Add the following to your user `settings.json` file:
+
+```json
+{
+  "security": {
+    "folderTrust": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## How it works: The trust dialog
+
+Once the feature is enabled, the first time you run the Gemini CLI from a
+folder, a dialog will automatically appear, prompting you to make a choice:
+
+- **Trust folder**: Grants full trust to the current folder (e.g.,
+  `my-project`).
+- **Trust parent folder**: Grants trust to the parent directory (e.g.,
+  `safe-projects`), which automatically trusts all of its subdirectories as
+  well. This is useful if you keep all your safe projects in one place.
+- **Don't trust**: Marks the folder as untrusted. The CLI will operate in a
+  restricted "safe mode."
+
+Your choice is saved in a central file (`~/.gemini/trustedFolders.json`), so you
+will only be asked once per folder.
+
+## Understanding folder contents: The discovery phase
+
+Before you make a choice, the Gemini CLI performs a **discovery phase** to scan
+the folder for potential configurations. This information is displayed in the
+trust dialog to help you make an informed decision.
+
+The discovery UI lists the following categories of items found in the project:
+
+- **Commands**: Custom `.toml` command definitions that add new functionality.
+- **MCP Servers**: Configured Model Context Protocol servers that the CLI will
+  attempt to connect to.
+- **Hooks**: System or custom hooks that can intercept and modify CLI behavior.
+- **Skills**: Local agent skills that provide specialized capabilities.
+- **Setting overrides**: Any project-specific configurations that override your
+  global user settings.
+
+### Security warnings and errors
+
+The trust dialog also highlights critical information that requires your
+attention:
+
+- **Security Warnings**: The CLI will explicitly flag potentially dangerous
+  settings, such as auto-approving certain tools or disabling the security
+  sandbox.
+- **Discovery Errors**: If the CLI encounters issues while scanning the folder
+  (e.g., a malformed `settings.json` file), these errors will be displayed
+  prominently.
+
+By reviewing these details, you can ensure that you only grant trust to projects
+that you know are safe.
+
+## Why trust matters: The impact of an untrusted workspace
+
+When a folder is **untrusted**, the Gemini CLI runs in a restricted "safe mode"
+to protect you. In this mode, the following features are disabled:
+
+1.  **Workspace settings are ignored**: The CLI will **not** load the
+    `.gemini/settings.json` file from the project. This prevents the loading of
+    custom tools and other potentially dangerous configurations.
+
+2.  **Environment variables are ignored**: The CLI will **not** load any `.env`
+    files from the project.
+
+3.  **Extension management is restricted**: You **cannot install, update, or
+    uninstall** extensions.
+
+4.  **Tool auto-acceptance is disabled**: You will always be prompted before any
+    tool is run, even if you have auto-acceptance enabled globally.
+
+5.  **Automatic memory loading is disabled**: The CLI will not automatically
+    load files into context from directories specified in local settings.
+
+6.  **MCP servers do not connect**: The CLI will not attempt to connect to any
+    [Model Context Protocol (MCP)](../tools/mcp-server.md) servers.
+
+7.  **Custom commands are not loaded**: The CLI will not load any custom
+    commands from .toml files, including both project-specific and global user
+    commands.
+
+Granting trust to a folder unlocks the full functionality of the Gemini CLI for
+that workspace.
+
+## Managing your trust settings
+
+If you need to change a decision or see all your settings, you have a couple of
+options:
+
+- **Change the current folder's trust**: Run the `/permissions` command from
+  within the CLI. This will bring up the same interactive dialog, allowing you
+  to change the trust level for the current folder.
+
+- **View all trust rules**: To see a complete list of all your trusted and
+  untrusted folder rules, you can inspect the contents of the
+  `~/.gemini/trustedFolders.json` file in your home directory.
+
+## The trust check process (advanced)
+
+For advanced users, it's helpful to know the exact order of operations for how
+trust is determined:
+
+1.  **IDE trust signal**: If you are using the
+    [IDE Integration](../ide-integration/index.md), the CLI first asks the IDE
+    if the workspace is trusted. The IDE's response takes highest priority.
+
+2.  **Local trust file**: If the IDE is not connected, the CLI checks the
+    central `~/.gemini/trustedFolders.json` file.

package/bundle/docs/cli/tutorials/automation.md

@@ -0,0 +1,283 @@
+# Automate tasks with headless mode
+
+Automate tasks with Gemini CLI. Learn how to use headless mode, pipe data into
+Gemini CLI, automate workflows with shell scripts, and generate structured JSON
+output for other applications.
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated.
+- Familiarity with shell scripting (Bash/Zsh).
+
+## Why headless mode?
+
+Headless mode runs Gemini CLI once and exits. It's perfect for:
+
+- **CI/CD:** Analyzing pull requests automatically.
+- **Batch processing:** Summarizing a large number of log files.
+- **Tool building:** Creating your own "AI wrapper" scripts.
+
+## How to use headless mode
+
+Run Gemini CLI in headless mode by providing a prompt as a positional argument.
+This bypasses the interactive chat interface and prints the response to standard
+output (stdout).
+
+Run a single command:
+
+```bash
+gemini "Write a poem about TypeScript"
+```
+
+## How to pipe input to Gemini CLI
+
+Feed data into Gemini using the standard Unix pipe `|`. Gemini reads the
+standard input (stdin) as context and answers your question using standard
+output.
+
+Pipe a file:
+
+**macOS/Linux**
+
+```bash
+cat error.log | gemini "Explain why this failed"
+```
+
+**Windows (PowerShell)**
+
+```powershell
+Get-Content error.log | gemini "Explain why this failed"
+```
+
+Pipe a command:
+
+```bash
+git diff | gemini "Write a commit message for these changes"
+```
+
+## Use Gemini CLI output in scripts
+
+Because Gemini prints to stdout, you can chain it with other tools or save the
+results to a file.
+
+### Scenario: Bulk documentation generator
+
+You have a folder of Python scripts and want to generate a `README.md` for each
+one.
+
+1.  Save the following code as `generate_docs.sh` (or `generate_docs.ps1` for
+    Windows):
+
+    **macOS/Linux (`generate_docs.sh`)**
+
+    ```bash
+    #!/bin/bash
+
+    # Loop through all Python files
+    for file in *.py; do
+      echo "Generating docs for $file..."
+
+      # Ask Gemini CLI to generate the documentation and print it to stdout
+      gemini "Generate a Markdown documentation summary for @$file. Print the
+      result to standard output." > "${file%.py}.md"
+    done
+    ```
+
+    **Windows PowerShell (`generate_docs.ps1`)**
+
+    ```powershell
+    # Loop through all Python files
+    Get-ChildItem -Filter *.py | ForEach-Object {
+      Write-Host "Generating docs for $($_.Name)..."
+
+      $newName = $_.Name -replace '\.py$', '.md'
+      # Ask Gemini CLI to generate the documentation and print it to stdout
+      gemini "Generate a Markdown documentation summary for @$($_.Name). Print the result to standard output." | Out-File -FilePath $newName -Encoding utf8
+    }
+    ```
+
+2.  Make the script executable and run it in your directory:
+
+    **macOS/Linux**
+
+    ```bash
+    chmod +x generate_docs.sh
+    ./generate_docs.sh
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    .\generate_docs.ps1
+    ```
+
+    This creates a corresponding Markdown file for every Python file in the
+    folder.
+
+## Extract structured JSON data
+
+When writing a script, you often need structured data (JSON) to pass to tools
+like `jq`. To get pure JSON data from the model, combine the
+`--output-format json` flag with `jq` to parse the response field.
+
+### Scenario: Extract and return structured data
+
+1.  Save the following script as `generate_json.sh` (or `generate_json.ps1` for
+    Windows):
+
+    **macOS/Linux (`generate_json.sh`)**
+
+    ```bash
+    #!/bin/bash
+
+    # Ensure we are in a project root
+    if [ ! -f "package.json" ]; then
+      echo "Error: package.json not found."
+      exit 1
+    fi
+
+    # Extract data
+    gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | jq -r '.response' > data.json
+    ```
+
+    **Windows PowerShell (`generate_json.ps1`)**
+
+    ```powershell
+    # Ensure we are in a project root
+    if (-not (Test-Path "package.json")) {
+      Write-Error "Error: package.json not found."
+      exit 1
+    }
+
+    # Extract data (requires jq installed, or you can use ConvertFrom-Json)
+    $output = gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | ConvertFrom-Json
+    $output.response | Out-File -FilePath data.json -Encoding utf8
+    ```
+
+2.  Run the script:
+
+    **macOS/Linux**
+
+    ```bash
+    chmod +x generate_json.sh
+    ./generate_json.sh
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    .\generate_json.ps1
+    ```
+
+3.  Check `data.json`. The file should look like this:
+
+    ```json
+    {
+      "version": "1.0.0",
+      "deps": {
+        "react": "^18.2.0"
+      }
+    }
+    ```
+
+## Build your own custom AI tools
+
+Use headless mode to perform custom, automated AI tasks.
+
+### Scenario: Create a "Smart Commit" alias
+
+You can add a function to your shell configuration to create a `git commit`
+wrapper that writes the message for you.
+
+**macOS/Linux (Bash/Zsh)**
+
+1.  Open your `.zshrc` file (or `.bashrc` if you use Bash) in your preferred
+    text editor.
+
+    ```bash
+    nano ~/.zshrc
+    ```
+
+    **Note**: If you use VS Code, you can run `code ~/.zshrc`.
+
+2.  Scroll to the very bottom of the file and paste this code:
+
+    ```bash
+    function gcommit() {
+      # Get the diff of staged changes
+      diff=$(git diff --staged)
+
+      if [ -z "$diff" ]; then
+        echo "No staged changes to commit."
+        return 1
+      fi
+
+      # Ask Gemini to write the message
+      echo "Generating commit message..."
+      msg=$(echo "$diff" | gemini "Write a concise Conventional Commit message for this diff. Output ONLY the message.")
+
+      # Commit with the generated message
+      git commit -m "$msg"
+    }
+    ```
+
+    Save your file and exit.
+
+3.  Run this command to make the function available immediately:
+
+    ```bash
+    source ~/.zshrc
+    ```
+
+**Windows (PowerShell)**
+
+1.  Open your PowerShell profile in your preferred text editor.
+
+    ```powershell
+    notepad $PROFILE
+    ```
+
+2.  Scroll to the very bottom of the file and paste this code:
+
+    ```powershell
+    function gcommit {
+      # Get the diff of staged changes
+      $diff = git diff --staged
+
+      if (-not $diff) {
+        Write-Host "No staged changes to commit."
+        return
+      }
+
+      # Ask Gemini to write the message
+      Write-Host "Generating commit message..."
+      $msg = $diff | gemini "Write a concise Conventional Commit message for this diff. Output ONLY the message."
+
+      # Commit with the generated message
+      git commit -m "$msg"
+    }
+    ```
+
+    Save your file and exit.
+
+3.  Run this command to make the function available immediately:
+
+    ```powershell
+    . $PROFILE
+    ```
+
+4.  Use your new command:
+
+    ```bash
+    gcommit
+    ```
+
+    Gemini CLI will analyze your staged changes and commit them with a generated
+    message.
+
+## Next steps
+
+- Explore the [Headless mode reference](../../cli/headless.md) for full JSON
+  schema details.
+- Learn about [Shell commands](shell-commands.md) to let the agent run scripts
+  instead of just writing them.