@dgxo/mashadevcli 1.1.0

package/bundle/docs/cli/tutorials/file-management.md

@@ -0,0 +1,142 @@
+# File management with Gemini CLI
+
+Explore, analyze, and modify your codebase using Gemini CLI. In this guide,
+you'll learn how to provide Gemini CLI with files and directories, modify and
+create files, and control what Gemini CLI can see.
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated.
+- A project directory to work with (e.g., a git repository).
+
+## How to give the agent context (Reading files)
+
+Gemini CLI will generally try to read relevant files, sometimes prompting you
+for access (depending on your settings). To ensure that Gemini CLI uses a file,
+you can also include it directly.
+
+### Direct file inclusion (`@`)
+
+If you know the path to the file you want to work on, use the `@` symbol. This
+forces the CLI to read the file immediately and inject its content into your
+prompt.
+
+```bash
+`@src/components/UserProfile.tsx Explain how this component handles user data.`
+```
+
+### Working with multiple files
+
+Complex features often span multiple files. You can chain `@` references to give
+the agent a complete picture of the dependencies.
+
+```bash
+`@src/components/UserProfile.tsx @src/types/User.ts Refactor the component to use the updated User interface.`
+```
+
+### Including entire directories
+
+For broad questions or refactoring, you can include an entire directory. Be
+careful with large folders, as this consumes more tokens.
+
+```bash
+`@src/utils/ Check these utility functions for any deprecated API usage.`
+```
+
+## How to find files (Exploration)
+
+If you _don't_ know the exact file path, you can ask Gemini CLI to find it for
+you. This is useful when navigating a new codebase or looking for specific
+logic.
+
+### Scenario: Find a component definition
+
+You know there's a `UserProfile` component, but you don't know where it lives.
+
+```none
+`Find the file that defines the UserProfile component.`
+```
+
+Gemini uses the `glob` or `list_directory` tools to search your project
+structure. It will return the specific path (e.g.,
+`src/components/UserProfile.tsx`), which you can then use with `@` in your next
+turn.
+
+> **Tip:** You can also ask for lists of files, like "Show me all the TypeScript
+> configuration files in the root directory."
+
+## How to modify code
+
+Once Gemini CLI has context, you can direct it to make specific edits. The agent
+is capable of complex refactoring, not just simple text replacement.
+
+```none
+`Update @src/components/UserProfile.tsx to show a loading spinner if the user data is null.`
+```
+
+Gemini CLI uses the `replace` tool to propose a targeted code change.
+
+### Creating new files
+
+You can also ask the agent to create entirely new files or folder structures.
+
+```none
+`Create a new file @src/components/LoadingSpinner.tsx with a simple Tailwind CSS spinner.`
+```
+
+Gemini CLI uses the `write_file` tool to generate the new file from scratch.
+
+## Review and confirm changes
+
+Gemini CLI prioritizes safety. Before any file is modified, it presents a
+unified diff of the proposed changes.
+
+```diff
+- if (!user) return null;
++ if (!user) return <LoadingSpinner />;
+```
+
+- **Red lines (-):** Code that will be removed.
+- **Green lines (+):** Code that will be added.
+
+Press **y** to confirm and apply the change to your local file system. If the
+diff doesn't look right, press **n** to cancel and refine your prompt.
+
+## Verify the result
+
+After the edit is complete, verify the fix. You can simply read the file again
+or, better yet, run your project's tests.
+
+```none
+`Run the tests for the UserProfile component.`
+```
+
+Gemini CLI uses the `run_shell_command` tool to execute your test runner (e.g.,
+`npm test` or `jest`). This ensures the changes didn't break existing
+functionality.
+
+## Advanced: Controlling what Gemini sees
+
+By default, Gemini CLI respects your `.gitignore` file. It won't read or search
+through `node_modules`, build artifacts, or other ignored paths.
+
+If you have sensitive files (like `.env`) or large assets that you want to keep
+hidden from the AI _without_ ignoring them in Git, you can create a
+`.geminiignore` file in your project root.
+
+**Example `.geminiignore`:**
+
+```text
+.env
+local-db-dump.sql
+private-notes.md
+```
+
+## Next steps
+
+- Learn how to [Manage context and memory](memory-management.md) to keep your
+  agent smarter over long sessions.
+- See [Execute shell commands](shell-commands.md) for more on running tests and
+  builds.
+- Explore the technical [File system reference](../../tools/file-system.md) for
+  advanced tool parameters.

package/bundle/docs/cli/tutorials/mcp-setup.md

@@ -0,0 +1,113 @@
+# Set up an MCP server
+
+Connect Gemini CLI to your external databases and services. In this guide,
+you'll learn how to extend Gemini CLI's capabilities by installing the GitHub
+MCP server and using it to manage your repositories.
+
+## Prerequisites
+
+- Gemini CLI installed.
+- **Docker:** Required for this specific example (many MCP servers run as Docker
+  containers).
+- **GitHub token:** A Personal Access Token (PAT) with repo permissions.
+
+## How to prepare your credentials
+
+Most MCP servers require authentication. For GitHub, you need a PAT.
+
+1.  Create a [fine-grained PAT](https://github.com/settings/tokens?type=beta).
+2.  Grant it **Read** access to **Metadata** and **Contents**, and
+    **Read/Write** access to **Issues** and **Pull Requests**.
+3.  Store it in your environment:
+
+**macOS/Linux**
+
+```bash
+export GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."
+```
+
+**Windows (PowerShell)**
+
+```powershell
+$env:GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."
+```
+
+## How to configure Gemini CLI
+
+You tell Gemini about new servers by editing your `settings.json`.
+
+1.  Open `~/.gemini/settings.json` (or the project-specific
+    `.gemini/settings.json`).
+2.  Add the `mcpServers` block. This tells Gemini: "Run this docker container
+    and talk to it."
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/modelcontextprotocol/servers/github:latest"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+> **Note:** The `command` is `docker`, and the rest are arguments passed to it.
+> We map the local environment variable into the container so your secret isn't
+> hardcoded in the config file.
+
+## How to verify the connection
+
+Restart Gemini CLI. It will automatically try to start the defined servers.
+
+**Command:** `/mcp list`
+
+You should see: `✓ github: docker ... - Connected`
+
+If you see `Disconnected` or an error, check that Docker is running and your API
+token is valid.
+
+## How to use the new tools
+
+Now that the server is running, the agent has new capabilities ("tools"). You
+don't need to learn special commands; just ask in natural language.
+
+### Scenario: Listing pull requests
+
+**Prompt:** `List the open PRs in the google/gemini-cli repository.`
+
+The agent will:
+
+1.  Recognize the request matches a GitHub tool.
+2.  Call `github_list_pull_requests`.
+3.  Present the data to you.
+
+### Scenario: Creating an issue
+
+**Prompt:**
+`Create an issue in my repo titled "Bug: Login fails" with the description "See logs".`
+
+## Troubleshooting
+
+- **Server won't start?** Try running the docker command manually in your
+  terminal to see if it prints an error (e.g., "image not found").
+- **Tools not found?** Run `/mcp refresh` to force the CLI to re-query the
+  server for its capabilities.
+
+## Next steps
+
+- Explore the [MCP servers reference](../../tools/mcp-server.md) to learn about
+  SSE and HTTP transports for remote servers.
+- Browse the
+  [official MCP server list](https://github.com/modelcontextprotocol/servers) to
+  find connectors for Slack, Postgres, Google Drive, and more.

package/bundle/docs/cli/tutorials/memory-management.md

@@ -0,0 +1,126 @@
+# Manage context and memory
+
+Control what Gemini CLI knows about you and your projects. In this guide, you'll
+learn how to define project-wide rules with `GEMINI.md`, teach the agent
+persistent facts, and inspect the active context.
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated.
+- A project directory where you want to enforce specific rules.
+
+## Why manage context?
+
+Out of the box, Gemini CLI is smart but generic. It doesn't know your preferred
+testing framework, your indentation style, or that you hate using `any` in
+TypeScript. Context management solves this by giving the agent persistent
+memory.
+
+You'll use these features when you want to:
+
+- **Enforce standards:** Ensure every generated file matches your team's style
+  guide.
+- **Set a persona:** Tell the agent to act as a "Senior Rust Engineer" or "QA
+  Specialist."
+- **Remember facts:** Save details like "My database port is 5432" so you don't
+  have to repeat them.
+
+## How to define project-wide rules (GEMINI.md)
+
+The most powerful way to control the agent's behavior is through `GEMINI.md`
+files. These are Markdown files containing instructions that are automatically
+loaded into every conversation.
+
+### Scenario: Create a project context file
+
+1.  In the root of your project, create a file named `GEMINI.md`.
+
+2.  Add your instructions:
+
+    ```markdown
+    # Project Instructions
+
+    - **Framework:** We use React with Vite.
+    - **Styling:** Use Tailwind CSS for all styling. Do not write custom CSS.
+    - **Testing:** All new components must include a Vitest unit test.
+    - **Tone:** Be concise. Don't explain basic React concepts.
+    ```
+
+3.  Start a new session. Gemini CLI will now know these rules automatically.
+
+### Scenario: Using the hierarchy
+
+Context is loaded hierarchically. This allows you to have general rules for
+everything and specific rules for sub-projects.
+
+1.  **Global:** `~/.gemini/GEMINI.md` (Rules for _every_ project you work on).
+2.  **Project Root:** `./GEMINI.md` (Rules for the current repository).
+3.  **Subdirectory:** `./src/GEMINI.md` (Rules specific to the `src` folder).
+
+**Example:** You might set "Always use strict typing" in your global config, but
+"Use Python 3.11" only in your backend repository.
+
+## How to teach the agent facts (Memory)
+
+Sometimes you don't want to write a config file. You just want to tell the agent
+something once and have it remember forever. You can do this naturally in chat.
+
+### Scenario: Saving a memory
+
+Just tell the agent to remember something.
+
+**Prompt:** `Remember that I prefer using 'const' over 'let' wherever possible.`
+
+The agent will use the `save_memory` tool to store this fact in your global
+memory file.
+
+**Prompt:** `Save the fact that the staging server IP is 10.0.0.5.`
+
+### Scenario: Using memory in conversation
+
+Once a fact is saved, you don't need to invoke it explicitly. The agent "knows"
+it.
+
+**Next Prompt:** `Write a script to deploy to staging.`
+
+**Agent Response:** "I'll write a script to deploy to **10.0.0.5**..."
+
+## How to manage and inspect context
+
+As your project grows, you might want to see exactly what instructions the agent
+is following.
+
+### Scenario: View active context
+
+To see the full, concatenated set of instructions currently loaded (from all
+`GEMINI.md` files and saved memories), use the `/memory show` command.
+
+**Command:** `/memory show`
+
+This prints the raw text the model receives at the start of the session. It's
+excellent for debugging why the agent might be ignoring a rule.
+
+### Scenario: Refresh context
+
+If you edit a `GEMINI.md` file while a session is running, the agent won't know
+immediately. Force a reload with:
+
+**Command:** `/memory refresh`
+
+## Best practices
+
+- **Keep it focused:** Don't dump your entire internal wiki into `GEMINI.md`.
+  Keep instructions actionable and relevant to code generation.
+- **Use negative constraints:** Explicitly telling the agent what _not_ to do
+  (e.g., "Do not use class components") is often more effective than vague
+  positive instructions.
+- **Review often:** Periodically check your `GEMINI.md` files to remove outdated
+  rules.
+
+## Next steps
+
+- Learn about [Session management](session-management.md) to see how short-term
+  history works.
+- Explore the [Command reference](../../reference/commands.md) for more
+  `/memory` options.
+- Read the technical spec for [Project context](../../cli/gemini-md.md).

package/bundle/docs/cli/tutorials/session-management.md

@@ -0,0 +1,105 @@
+# Manage sessions and history
+
+Resume, browse, and rewind your conversations with Gemini CLI. In this guide,
+you'll learn how to switch between tasks, manage your session history, and undo
+mistakes using the rewind feature.
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated.
+- At least one active or past session.
+
+## How to resume where you left off
+
+It's common to switch context—maybe you're waiting for a build and want to work
+on a different feature. Gemini makes it easy to jump back in.
+
+### Scenario: Resume the last session
+
+The fastest way to pick up your most recent work is with the `--resume` flag (or
+`-r`).
+
+```bash
+gemini -r
+```
+
+This restores your chat history and memory, so you can say "Continue with the
+next step" immediately.
+
+### Scenario: Browse past sessions
+
+If you want to find a specific conversation from yesterday, use the interactive
+browser.
+
+**Command:** `/resume`
+
+This opens a searchable list of all your past sessions. You'll see:
+
+- A timestamp (e.g., "2 hours ago").
+- The first user message (helping you identify the topic).
+- The number of turns in the conversation.
+
+Select a session and press **Enter** to load it.
+
+## How to manage your workspace
+
+Over time, you'll accumulate a lot of history. Keeping your session list clean
+helps you find what you need.
+
+### Scenario: Deleting sessions
+
+In the `/resume` browser, navigate to a session you no longer need and press
+**x**. This permanently deletes the history for that specific conversation.
+
+You can also manage sessions from the command line:
+
+```bash
+# List all sessions with their IDs
+gemini --list-sessions
+
+# Delete a specific session by ID or index
+gemini --delete-session 1
+```
+
+## How to rewind time (Undo mistakes)
+
+Gemini CLI's **Rewind** feature is like `Ctrl+Z` for your workflow.
+
+### Scenario: Triggering rewind
+
+At any point in a chat, type `/rewind` or press **Esc** twice.
+
+### Scenario: Choosing a restore point
+
+You'll see a list of your recent interactions. Select the point _before_ the
+undesired changes occurred.
+
+### Scenario: Choosing what to revert
+
+Gemini gives you granular control over the undo process. You can choose to:
+
+1.  **Rewind conversation:** Only remove the chat history. The files stay
+    changed. (Useful if the code is good but the chat got off track).
+2.  **Revert code changes:** Keep the chat history but undo the file edits.
+    (Useful if you want to keep the context but retry the implementation).
+3.  **Rewind both:** Restore everything to exactly how it was.
+
+## How to fork conversations
+
+Sometimes you want to try two different approaches to the same problem.
+
+1.  Start a session and get to a decision point.
+2.  Save the current state with `/chat save decision-point`.
+3.  Try your first approach.
+4.  Later, use `/chat resume decision-point` to fork the conversation back to
+    that moment and try a different approach.
+
+This creates a new branch of history without losing your original work.
+
+## Next steps
+
+- Learn about [Checkpointing](../../cli/checkpointing.md) to understand the
+  underlying safety mechanism.
+- Explore [Task planning](task-planning.md) to keep complex sessions organized.
+- See the [Command reference](../../reference/commands.md) for all `/chat` and
+  `/resume` options.

package/bundle/docs/cli/tutorials/shell-commands.md

@@ -0,0 +1,107 @@
+# Execute shell commands
+
+Use the CLI to run builds, manage git, and automate system tasks without leaving
+the conversation. In this guide, you'll learn how to run commands directly,
+automate complex workflows, and manage background processes safely.
+
+## Prerequisites
+
+- Gemini CLI installed and authenticated.
+- Basic familiarity with your system's shell (Bash, Zsh, PowerShell, etc.).
+
+## How to run commands directly (`!`)
+
+Sometimes you just need to check a file size or git status without asking the AI
+to do it for you. You can pass commands directly to your shell using the `!`
+prefix.
+
+**Example:** `!ls -la`
+
+This executes `ls -la` immediately and prints the output to your terminal. The
+AI doesn't "see" this output unless you paste it back into the chat or use it in
+a prompt.
+
+### Scenario: Entering Shell mode
+
+If you're doing a lot of manual work, toggle "Shell Mode" by typing `!` and
+pressing **Enter**. Now, everything you type is sent to the shell until you exit
+(usually by pressing **Esc** or typing `exit`).
+
+## How to automate complex tasks
+
+You can automate tasks using a combination of Gemini CLI and shell commands.
+
+### Scenario: Run tests and fix failures
+
+You want to run tests and fix any failures.
+
+**Prompt:**
+`Run the unit tests. If any fail, analyze the error and try to fix the code.`
+
+**Workflow:**
+
+1.  Gemini calls `run_shell_command('npm test')`.
+2.  You see a confirmation prompt: `Allow command 'npm test'? [y/N]`.
+3.  You press `y`.
+4.  The tests run. If they fail, Gemini reads the error output.
+5.  Gemini uses `read_file` to inspect the failing test.
+6.  Gemini uses `replace` to fix the bug.
+7.  Gemini runs `npm test` again to verify the fix.
+
+This loop turns Gemini into an autonomous engineer.
+
+## How to manage background processes
+
+You can ask Gemini to start long-running tasks, like development servers or file
+watchers.
+
+**Prompt:** `Start the React dev server in the background.`
+
+Gemini will run the command (e.g., `npm run dev`) and detach it.
+
+### Scenario: Viewing active shells
+
+To see what's running in the background, use the `/shells` command.
+
+**Command:** `/shells`
+
+This opens a dashboard where you can view logs or kill runaway processes.
+
+## How to handle interactive commands
+
+Gemini CLI attempts to handle interactive commands (like `git add -p` or
+confirmation prompts) by streaming the output to you. However, for highly
+interactive tools (like `vim` or `top`), it's often better to run them yourself
+in a separate terminal window or use the `!` prefix.
+
+## Safety first
+
+Giving an AI access to your shell is powerful but risky. Gemini CLI includes
+several safety layers.
+
+### Confirmation prompts
+
+By default, **every** shell command requested by the agent requires your
+explicit approval.
+
+- **Allow once:** Runs the command one time.
+- **Allow always:** Trusts this specific command for the rest of the session.
+- **Deny:** Stops the agent.
+
+### Sandboxing
+
+For maximum security, especially when running untrusted code or exploring new
+projects, we strongly recommend enabling Sandboxing. This runs all shell
+commands inside a secure Docker container.
+
+**Enable sandboxing:** Use the `--sandbox` flag when starting the CLI:
+`gemini --sandbox`.
+
+## Next steps
+
+- Learn about [Sandboxing](../../cli/sandbox.md) to safely run destructive
+  commands.
+- See the [Shell tool reference](../../tools/shell.md) for configuration options
+  like timeouts and working directories.
+- Explore [Task planning](task-planning.md) to see how shell commands fit into
+  larger workflows.

package/bundle/docs/cli/tutorials/skills-getting-started.md

@@ -0,0 +1,110 @@
+# Get started with Agent Skills
+
+Agent Skills extend Gemini CLI with specialized expertise. In this guide, you'll
+learn how to create your first skill, bundle custom scripts, and activate them
+during a session.
+
+## How to create a skill
+
+A skill is defined by a directory containing a `SKILL.md` file. Let's create an
+**API Auditor** skill that helps you verify if local or remote endpoints are
+responding correctly.
+
+### Create the directory structure
+
+1.  Run the following command to create the folders:
+
+    **macOS/Linux**
+
+    ```bash
+    mkdir -p .gemini/skills/api-auditor/scripts
+    ```
+
+    **Windows (PowerShell)**
+
+    ```powershell
+    New-Item -ItemType Directory -Force -Path ".gemini\skills\api-auditor\scripts"
+    ```
+
+### Create the definition
+
+1.  Create a file at `.gemini/skills/api-auditor/SKILL.md`. This tells the agent
+    _when_ to use the skill and _how_ to behave.
+
+    ```markdown
+    ---
+    name: api-auditor
+    description:
+      Expertise in auditing and testing API endpoints. Use when the user asks to
+      "check", "test", or "audit" a URL or API.
+    ---
+
+    # API Auditor Instructions
+
+    You act as a QA engineer specialized in API reliability. When this skill is
+    active, you MUST:
+
+    1.  **Audit**: Use the bundled `scripts/audit.js` utility to check the
+        status of the provided URL.
+    2.  **Report**: Analyze the output (status codes, latency) and explain any
+        failures in plain English.
+    3.  **Secure**: Remind the user if they are testing a sensitive endpoint
+        without an `https://` protocol.
+    ```
+
+### Add the tool logic
+
+Skills can bundle resources like scripts.
+
+1.  Create a file at `.gemini/skills/api-auditor/scripts/audit.js`. This is the
+    code the agent will run.
+
+    ```javascript
+    // .gemini/skills/api-auditor/scripts/audit.js
+    const url = process.argv[2];
+
+    if (!url) {
+      console.error('Usage: node audit.js <url>');
+      process.exit(1);
+    }
+
+    console.log(`Auditing ${url}...`);
+    fetch(url, { method: 'HEAD' })
+      .then((r) => console.log(`Result: Success (Status ${r.status})`))
+      .catch((e) => console.error(`Result: Failed (${e.message})`));
+    ```
+
+## How to verify discovery
+
+Gemini CLI automatically discovers skills in the `.gemini/skills` directory. You
+can also use `.agents/skills` as a more generic alternative. Check that it found
+your new skill.
+
+**Command:** `/skills list`
+
+You should see `api-auditor` in the list of available skills.
+
+## How to use the skill
+
+Now, try it out. Start a new session and ask a question that triggers the
+skill's description.
+
+**User:** "Can you audit http://geminicli.com"
+
+Gemini recognizes the request matches the `api-auditor` description and asks for
+permission to activate it.
+
+**Model:** (After calling `activate_skill`) "I've activated the **api-auditor**
+skill. I'll run the audit script now..."
+
+Gemini then uses the `run_shell_command` tool to execute your bundled Node
+script:
+
+`node .gemini/skills/api-auditor/scripts/audit.js http://geminili.com`
+
+## Next steps
+
+- Explore the
+  [Agent Skills Authoring Guide](../../cli/skills.md#creating-a-skill) to learn
+  about more advanced features.
+- Learn how to share skills via [Extensions](../../extensions/index.md).