@terminai/core 0.21.0

package/dist/docs/cli/generation-settings.md

@@ -0,0 +1,210 @@
+# Advanced Model Configuration
+
+This guide details the Model Configuration system within the Gemini CLI.
+Designed for researchers, AI quality engineers, and advanced users, this system
+provides a rigorous framework for managing generative model hyperparameters and
+behaviors.
+
+> **Warning**: This is a power-user feature. Configuration values are passed
+> directly to the model provider with minimal validation. Incorrect settings
+> (e.g., incompatible parameter combinations) may result in runtime errors from
+> the API.
+
+## 1. System Overview
+
+The Model Configuration system (`ModelConfigService`) enables deterministic
+control over model generation. It decouples the requested model identifier
+(e.g., a CLI flag or agent request) from the underlying API configuration. This
+allows for:
+
+- **Precise Hyperparameter Tuning**: Direct control over `temperature`, `topP`,
+  `thinkingBudget`, and other SDK-level parameters.
+- **Environment-Specific Behavior**: Distinct configurations for different
+  operating contexts (e.g., testing vs. production).
+- **Agent-Scoped Customization**: Applying specific settings only when a
+  particular agent is active.
+
+The system operates on two core primitives: **Aliases** and **Overrides**.
+
+## 2. Configuration Primitives
+
+These settings are located under the `modelConfigs` key in your configuration
+file.
+
+### Aliases (`customAliases`)
+
+Aliases are named, reusable configuration presets. Users should define their own
+aliases (or override system defaults) in the `customAliases` map.
+
+- **Inheritance**: An alias can `extends` another alias (including system
+  defaults like `chat-base`), inheriting its `modelConfig`. Child aliases can
+  overwrite or augment inherited settings.
+- **Abstract Aliases**: An alias is not required to specify a concrete `model`
+  if it serves purely as a base for other aliases.
+
+**Example Hierarchy**:
+
+```json
+"modelConfigs": {
+  "customAliases": {
+    "base": {
+      "modelConfig": {
+        "generateContentConfig": { "temperature": 0.0 }
+      }
+    },
+    "chat-base": {
+      "extends": "base",
+      "modelConfig": {
+        "generateContentConfig": { "temperature": 0.7 }
+      }
+    }
+  }
+}
+```
+
+### Overrides (`overrides`)
+
+Overrides are conditional rules that inject configuration based on the runtime
+context. They are evaluated dynamically for each model request.
+
+- **Match Criteria**: Overrides apply when the request context matches the
+  specified `match` properties.
+  - `model`: Matches the requested model name or alias.
+  - `overrideScope`: Matches the distinct scope of the request (typically the
+    agent name, e.g., `codebaseInvestigator`).
+
+**Example Override**:
+
+```json
+"modelConfigs": {
+  "overrides": [
+    {
+      "match": {
+        "overrideScope": "codebaseInvestigator"
+      },
+      "modelConfig": {
+        "generateContentConfig": { "temperature": 0.1 }
+      }
+    }
+  ]
+}
+```
+
+## 3. Resolution Strategy
+
+The `ModelConfigService` resolves the final configuration through a two-step
+process:
+
+### Step 1: Alias Resolution
+
+The requested model string is looked up in the merged map of system `aliases`
+and user `customAliases`.
+
+1.  If found, the system recursively resolves the `extends` chain.
+2.  Settings are merged from parent to child (child wins).
+3.  This results in a base `ResolvedModelConfig`.
+4.  If not found, the requested string is treated as the raw model name.
+
+### Step 2: Override Application
+
+The system evaluates the `overrides` list against the request context (`model`
+and `overrideScope`).
+
+1.  **Filtering**: All matching overrides are identified.
+2.  **Sorting**: Matches are prioritized by **specificity** (the number of
+    matched keys in the `match` object).
+    - Specific matches (e.g., `model` + `overrideScope`) override broad matches
+      (e.g., `model` only).
+    - Tie-breaking: If specificity is equal, the order of definition in the
+      `overrides` array is preserved (last one wins).
+3.  **Merging**: The configurations from the sorted overrides are merged
+    sequentially onto the base configuration.
+
+## 4. Configuration Reference
+
+The configuration follows the `ModelConfigServiceConfig` interface.
+
+### `ModelConfig` Object
+
+Defines the actual parameters for the model.
+
+| Property                | Type     | Description                                                        |
+| :---------------------- | :------- | :----------------------------------------------------------------- |
+| `model`                 | `string` | The identifier of the model to be called (e.g., `gemini-2.5-pro`). |
+| `generateContentConfig` | `object` | The configuration object passed to the `@google/genai` SDK.        |
+
+### `GenerateContentConfig` (Common Parameters)
+
+Directly maps to the SDK's `GenerateContentConfig`. Common parameters include:
+
+- **`temperature`**: (`number`) Controls output randomness. Lower values (0.0)
+  are deterministic; higher values (>0.7) are creative.
+- **`topP`**: (`number`) Nucleus sampling probability.
+- **`maxOutputTokens`**: (`number`) Limit on generated response length.
+- **`thinkingConfig`**: (`object`) Configuration for models with reasoning
+  capabilities (e.g., `thinkingBudget`, `includeThoughts`).
+
+## 5. Practical Examples
+
+### Defining a Deterministic Baseline
+
+Create an alias for tasks requiring high precision, extending the standard chat
+configuration but enforcing zero temperature.
+
+```json
+"modelConfigs": {
+  "customAliases": {
+    "precise-mode": {
+      "extends": "chat-base",
+      "modelConfig": {
+        "generateContentConfig": {
+          "temperature": 0.0,
+          "topP": 1.0
+        }
+      }
+    }
+  }
+}
+```
+
+### Agent-Specific Parameter Injection
+
+Enforce extended thinking budgets for a specific agent without altering the
+global default, e.g. for the `codebaseInvestigator`.
+
+```json
+"modelConfigs": {
+  "overrides": [
+    {
+      "match": {
+        "overrideScope": "codebaseInvestigator"
+      },
+      "modelConfig": {
+        "generateContentConfig": {
+          "thinkingConfig": { "thinkingBudget": 4096 }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Experimental Model Evaluation
+
+Route traffic for a specific alias to a preview model for A/B testing, without
+changing client code.
+
+```json
+"modelConfigs": {
+  "overrides": [
+    {
+      "match": {
+        "model": "gemini-2.5-pro"
+      },
+      "modelConfig": {
+        "model": "gemini-2.5-pro-experimental-001"
+      }
+    }
+  ]
+}
+```

package/dist/docs/cli/headless.md

@@ -0,0 +1,391 @@
+# Headless mode
+
+Headless mode allows you to run Gemini CLI programmatically from command line
+scripts and automation tools without any interactive UI. This is ideal for
+scripting, automation, CI/CD pipelines, and building AI-powered tools.
+
+> Note: The preferred binary name is `terminai`; the `gemini` alias is kept for
+> compatibility.
+
+- [Headless Mode](#headless-mode)
+  - [Overview](#overview)
+  - [Basic Usage](#basic-usage)
+    - [Direct Prompts](#direct-prompts)
+    - [Stdin Input](#stdin-input)
+    - [Combining with File Input](#combining-with-file-input)
+  - [Output Formats](#output-formats)
+    - [Text Output (Default)](#text-output-default)
+    - [JSON Output](#json-output)
+      - [Response Schema](#response-schema)
+      - [Example Usage](#example-usage)
+    - [Streaming JSON Output](#streaming-json-output)
+      - [When to Use Streaming JSON](#when-to-use-streaming-json)
+      - [Event Types](#event-types)
+      - [Basic Usage](#basic-usage)
+      - [Example Output](#example-output)
+      - [Processing Stream Events](#processing-stream-events)
+      - [Real-World Examples](#real-world-examples)
+    - [File Redirection](#file-redirection)
+  - [Configuration Options](#configuration-options)
+  - [Examples](#examples)
+    - [Code review](#code-review)
+    - [Generate commit messages](#generate-commit-messages)
+    - [API documentation](#api-documentation)
+    - [Batch code analysis](#batch-code-analysis)
+    - [Code review](#code-review-1)
+    - [Log analysis](#log-analysis)
+    - [Release notes generation](#release-notes-generation)
+    - [Model and tool usage tracking](#model-and-tool-usage-tracking)
+  - [Resources](#resources)
+
+## Overview
+
+The headless mode provides a headless interface to Gemini CLI that:
+
+- Accepts prompts via command line arguments or stdin
+- Returns structured output (text or JSON)
+- Supports file redirection and piping
+- Enables automation and scripting workflows
+- Provides consistent exit codes for error handling
+
+## Basic usage
+
+### Direct prompts
+
+Use the `--prompt` (or `-p`) flag to run in headless mode:
+
+```bash
+terminai --prompt "What is machine learning?"
+```
+
+### Stdin input
+
+Pipe input to Gemini CLI from your terminal:
+
+```bash
+echo "Explain this code" | terminai
+```
+
+### Combining with file input
+
+Read from files and process with Gemini:
+
+```bash
+cat README.md | terminai --prompt "Summarize this documentation"
+```
+
+## Output formats
+
+### Text output (default)
+
+Standard human-readable output:
+
+```bash
+terminai -p "What is the capital of France?"
+```
+
+Response format:
+
+```
+The capital of France is Paris.
+```
+
+### JSON output
+
+Returns structured data including response, statistics, and metadata. This
+format is ideal for programmatic processing and automation scripts.
+
+#### Response schema
+
+The JSON output follows this high-level structure:
+
+```json
+{
+  "response": "string", // The main AI-generated content answering your prompt
+  "stats": {
+    // Usage metrics and performance data
+    "models": {
+      // Per-model API and token usage statistics
+      "[model-name]": {
+        "api": {
+          /* request counts, errors, latency */
+        },
+        "tokens": {
+          /* prompt, response, cached, total counts */
+        }
+      }
+    },
+    "tools": {
+      // Tool execution statistics
+      "totalCalls": "number",
+      "totalSuccess": "number",
+      "totalFail": "number",
+      "totalDurationMs": "number",
+      "totalDecisions": {
+        /* accept, reject, modify, auto_accept counts */
+      },
+      "byName": {
+        /* per-tool detailed stats */
+      }
+    },
+    "files": {
+      // File modification statistics
+      "totalLinesAdded": "number",
+      "totalLinesRemoved": "number"
+    }
+  },
+  "error": {
+    // Present only when an error occurred
+    "type": "string", // Error type (e.g., "ApiError", "AuthError")
+    "message": "string", // Human-readable error description
+    "code": "number" // Optional error code
+  }
+}
+```
+
+#### Example usage
+
+```bash
+terminai -p "What is the capital of France?" --output-format json
+```
+
+Response:
+
+```json
+{
+  "response": "The capital of France is Paris.",
+  "stats": {
+    "models": {
+      "gemini-2.5-pro": {
+        "api": {
+          "totalRequests": 2,
+          "totalErrors": 0,
+          "totalLatencyMs": 5053
+        },
+        "tokens": {
+          "prompt": 24939,
+          "candidates": 20,
+          "total": 25113,
+          "cached": 21263,
+          "thoughts": 154,
+          "tool": 0
+        }
+      },
+      "gemini-2.5-flash": {
+        "api": {
+          "totalRequests": 1,
+          "totalErrors": 0,
+          "totalLatencyMs": 1879
+        },
+        "tokens": {
+          "prompt": 8965,
+          "candidates": 10,
+          "total": 9033,
+          "cached": 0,
+          "thoughts": 30,
+          "tool": 28
+        }
+      }
+    },
+    "tools": {
+      "totalCalls": 1,
+      "totalSuccess": 1,
+      "totalFail": 0,
+      "totalDurationMs": 1881,
+      "totalDecisions": {
+        "accept": 0,
+        "reject": 0,
+        "modify": 0,
+        "auto_accept": 1
+      },
+      "byName": {
+        "google_web_search": {
+          "count": 1,
+          "success": 1,
+          "fail": 0,
+          "durationMs": 1881,
+          "decisions": {
+            "accept": 0,
+            "reject": 0,
+            "modify": 0,
+            "auto_accept": 1
+          }
+        }
+      }
+    },
+    "files": {
+      "totalLinesAdded": 0,
+      "totalLinesRemoved": 0
+    }
+  }
+}
+```
+
+### Streaming JSON output
+
+Returns real-time events as newline-delimited JSON (JSONL). Each significant
+action (initialization, messages, tool calls, results) emits immediately as it
+occurs. This format is ideal for monitoring long-running operations, building
+UIs with live progress, and creating automation pipelines that react to events.
+
+#### When to use streaming JSON
+
+Use `--output-format stream-json` when you need:
+
+- **Real-time progress monitoring** - See tool calls and responses as they
+  happen
+- **Event-driven automation** - React to specific events (e.g., tool failures)
+- **Live UI updates** - Build interfaces showing AI agent activity in real-time
+- **Detailed execution logs** - Capture complete interaction history with
+  timestamps
+- **Pipeline integration** - Stream events to logging/monitoring systems
+
+#### Event types
+
+The streaming format emits 6 event types:
+
+1. **`init`** - Session starts (includes session_id, model)
+2. **`message`** - User prompts and assistant responses
+3. **`tool_use`** - Tool call requests with parameters
+4. **`tool_result`** - Tool execution results (success/error)
+5. **`error`** - Non-fatal errors and warnings
+6. **`result`** - Final session outcome with aggregated stats
+
+#### Basic usage
+
+```bash
+# Stream events to console
+terminai --output-format stream-json --prompt "What is 2+2?"
+
+# Save event stream to file
+terminai --output-format stream-json --prompt "Analyze this code" > events.jsonl
+
+# Parse with jq
+terminai --output-format stream-json --prompt "List files" | jq -r '.type'
+```
+
+#### Example output
+
+Each line is a complete JSON event:
+
+```jsonl
+{"type":"init","timestamp":"2025-10-10T12:00:00.000Z","session_id":"abc123","model":"gemini-2.0-flash-exp"}
+{"type":"message","role":"user","content":"List files in current directory","timestamp":"2025-10-10T12:00:01.000Z"}
+{"type":"tool_use","tool_name":"Bash","tool_id":"bash-123","parameters":{"command":"ls -la"},"timestamp":"2025-10-10T12:00:02.000Z"}
+{"type":"tool_result","tool_id":"bash-123","status":"success","output":"file1.txt\nfile2.txt","timestamp":"2025-10-10T12:00:03.000Z"}
+{"type":"message","role":"assistant","content":"Here are the files...","delta":true,"timestamp":"2025-10-10T12:00:04.000Z"}
+{"type":"result","status":"success","stats":{"total_tokens":250,"input_tokens":50,"output_tokens":200,"duration_ms":3000,"tool_calls":1},"timestamp":"2025-10-10T12:00:05.000Z"}
+```
+
+### File redirection
+
+Save output to files or pipe to other commands:
+
+```bash
+# Save to file
+terminai -p "Explain Docker" > docker-explanation.txt
+terminai -p "Explain Docker" --output-format json > docker-explanation.json
+
+# Append to file
+terminai -p "Add more details" >> docker-explanation.txt
+
+# Pipe to other tools
+terminai -p "What is Kubernetes?" --output-format json | jq '.response'
+terminai -p "Explain microservices" | wc -w
+terminai -p "List programming languages" | grep -i "python"
+```
+
+## Configuration options
+
+Key command-line options for headless usage:
+
+| Option                  | Description                        | Example                                              |
+| ----------------------- | ---------------------------------- | ---------------------------------------------------- |
+| `--prompt`, `-p`        | Run in headless mode               | `terminai -p "query"`                                |
+| `--output-format`       | Specify output format (text, json) | `terminai -p "query" --output-format json`           |
+| `--model`, `-m`         | Specify the Gemini model           | `terminai -p "query" -m gemini-2.5-flash`            |
+| `--debug`, `-d`         | Enable debug mode                  | `terminai -p "query" --debug`                        |
+| `--include-directories` | Include additional directories     | `terminai -p "query" --include-directories src,docs` |
+| `--yolo`, `-y`          | Auto-approve all actions           | `terminai -p "query" --yolo`                         |
+| `--approval-mode`       | Set approval mode                  | `terminai -p "query" --approval-mode auto_edit`      |
+
+For complete details on all available configuration options, settings files, and
+environment variables, see the
+[Configuration Guide](../get-started/configuration.md).
+
+## Examples
+
+#### Code review
+
+```bash
+cat src/auth.py | terminai -p "Review this authentication code for security issues" > security-review.txt
+```
+
+#### Generate commit messages
+
+```bash
+result=$(git diff --cached | terminai -p "Write a concise commit message for these changes" --output-format json)
+echo "$result" | jq -r '.response'
+```
+
+#### API documentation
+
+```bash
+result=$(cat api/routes.js | terminai -p "Generate OpenAPI spec for these routes" --output-format json)
+echo "$result" | jq -r '.response' > openapi.json
+```
+
+#### Batch code analysis
+
+```bash
+for file in src/*.py; do
+    echo "Analyzing $file..."
+    result=$(cat "$file" | terminai -p "Find potential bugs and suggest improvements" --output-format json)
+    echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis"
+    echo "Completed analysis for $(basename "$file")" >> reports/progress.log
+done
+```
+
+#### Code review
+
+```bash
+result=$(git diff origin/main...HEAD | terminai -p "Review these changes for bugs, security issues, and code quality" --output-format json)
+echo "$result" | jq -r '.response' > pr-review.json
+```
+
+#### Log analysis
+
+```bash
+grep "ERROR" /var/log/app.log | tail -20 | terminai -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt
+```
+
+#### Release notes generation
+
+```bash
+result=$(git log --oneline v1.0.0..HEAD | terminai -p "Generate release notes from these commits" --output-format json)
+response=$(echo "$result" | jq -r '.response')
+echo "$response"
+echo "$response" >> CHANGELOG.md
+```
+
+#### Model and tool usage tracking
+
+```bash
+result=$(terminai -p "Explain this database schema" --include-directories db --output-format json)
+total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
+models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
+tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
+tools_used=$(echo "$result" | jq -r '.stats.tools.byName // {} | keys | join(", ") | if . == "" then "none" else . end')
+echo "$(date): $total_tokens tokens, $tool_calls tool calls ($tools_used) used with models: $models_used" >> usage.log
+echo "$result" | jq -r '.response' > schema-docs.md
+echo "Recent usage trends:"
+tail -5 usage.log
+```
+
+## Resources
+
+- [CLI Configuration](../get-started/configuration.md) - Complete configuration
+  guide
+- [Authentication](../get-started/authentication.md) - Setup authentication
+- [Commands](./commands.md) - Interactive commands reference
+- [Tutorials](./tutorials.md) - Step-by-step automation guides

package/dist/docs/cli/index.md

@@ -0,0 +1,66 @@
+# Gemini CLI
+
+Within Gemini CLI, `packages/cli` is the frontend for users to send and receive
+prompts with the Gemini AI model and its associated tools. For a general
+overview of Gemini CLI, see the [main documentation page](../index.md).
+
+> Note: The preferred binary name is `terminai`; the `gemini` alias is kept for
+> compatibility.
+
+## Basic features
+
+- **[Commands](./commands.md):** A reference for all built-in slash commands
+- **[Custom commands](./custom-commands.md):** Create your own commands and
+  shortcuts for frequently used prompts.
+- **[Headless mode](./headless.md):** Use Gemini CLI programmatically for
+  scripting and automation.
+- **[Model selection](./model.md):** Configure the Gemini AI model used by the
+  CLI.
+- **[Settings](./settings.md):** Configure various aspects of the CLI's behavior
+  and appearance.
+- **[Themes](./themes.md):** Customizing the CLI's appearance with different
+  themes.
+- **[Keyboard shortcuts](./keyboard-shortcuts.md):** A reference for all
+  keyboard shortcuts to improve your workflow.
+- **[Tutorials](./tutorials.md):** Step-by-step guides for common tasks.
+
+## Advanced features
+
+- **[Checkpointing](./checkpointing.md):** Automatically save and restore
+  snapshots of your session and files.
+- **[Enterprise configuration](./enterprise.md):** Deploying and manage Gemini
+  CLI in an enterprise environment.
+- **[Sandboxing](./sandbox.md):** Isolate tool execution in a secure,
+  containerized environment.
+- **[Telemetry](./telemetry.md):** Configure observability to monitor usage and
+  performance.
+- **[Token caching](./token-caching.md):** Optimize API costs by caching tokens.
+- **[Trusted folders](./trusted-folders.md):** A security feature to control
+  which projects can use the full capabilities of the CLI.
+- **[Ignoring files (.geminiignore)](./gemini-ignore.md):** Exclude specific
+  files and directories from being accessed by tools.
+- **[Context files (terminaI.md)](./terminaI-md.md):** Provide persistent,
+  hierarchical context to the model.
+- **[System prompt override](./system-prompt.md):** Replace the built‑in system
+  instructions using `TERMINAI_SYSTEM_MD`.
+
+## Non-interactive mode
+
+Gemini CLI can be run in a non-interactive mode, which is useful for scripting
+and automation. In this mode, you pipe input to the CLI, it executes the
+command, and then it exits.
+
+The following example pipes a command to Gemini CLI from your terminal:
+
+```bash
+echo "What is fine tuning?" | terminai
+```
+
+You can also use the `--prompt` or `-p` flag:
+
+```bash
+terminai -p "What is fine tuning?"
+```
+
+For comprehensive documentation on headless usage, scripting, automation, and
+advanced examples, see the **[Headless mode](./headless.md)** guide.