> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grindxp.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Grind on macOS, Linux, or Windows using the installer script, Bun, or from source.

## Requirements

* **macOS** 12+, **Linux** (x86\_64 / arm64), or **Windows** 10+ (via WSL2 or PowerShell)
* [Bun](https://bun.sh) v1.0+ (required at runtime)

<Tip>
  Don't have Bun? Install it first: `curl -fsSL https://bun.sh/install | bash` On Windows:
  `powershell -c "irm bun.sh/install.ps1 | iex"`
</Tip>

<Warning>
  **Windows Users**: Grind has limited support on native Windows PowerShell. The Forge daemon,
  filesystem watchers, and process detection require a POSIX environment. For full functionality,
  use **WSL2** (Windows Subsystem for Linux 2). If you only need basic quest/XP tracking, native
  Windows works fine.
</Warning>

***

<AccordionGroup>
  <Accordion title="Installer script (recommended)" icon="terminal" defaultOpen>
    The fastest path. Downloads, installs, and runs the setup wizard automatically.

    <CodeGroup>
      ```bash macOS-Linux-WSL2 theme={null}
      curl -fsSL https://grindxp.app/install.sh | bash
      ```

      ```powershell Windows theme={null}
      iwr -useb https://grindxp.app/install.ps1 | iex
      ```
    </CodeGroup>

    The script:

    1. Detects your platform and architecture
    2. Downloads the latest Grind release
    3. Installs to `~/.grind/bin/` and adds it to your `PATH`
    4. Runs `grindxp init` to set up your vault

    To skip the setup wizard:

    <CodeGroup>
      ```bash macOS-Linux-WSL2 theme={null}
      curl -fsSL https://grindxp.app/install.sh | bash -s -- --no-init
      ```

      ```powershell Windows theme={null}
      & ([scriptblock]::Create((iwr -useb https://grindxp.app/install.ps1))) -NoInit
      ```
    </CodeGroup>

    <Note>
      WSL2 is recommended for full feature support (filesystem watchers, process detection, Forge daemon). The PowerShell installer installs into WSL2 by default if available.
    </Note>
  </Accordion>

  <Accordion title="Package manager (bun / npm / pnpm)" icon="package">
    <CodeGroup>
      ```bash bun theme={null}
      bun install -g grindxp
      ```

      ```bash npm theme={null}
      npm install -g grindxp
      ```

      ```bash pnpm theme={null}
      pnpm add -g grindxp
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="From source" icon="code">
    For contributors or users who want to track `main`.

    <Tabs>
      <Tab title="macOS / Linux">
        <Steps>
          <Step title="Install Bun">
            ```bash theme={null}
            curl -fsSL https://bun.sh/install | bash
            ```
          </Step>

          <Step title="Clone and install">
            ```bash theme={null}
            git clone https://github.com/esau-morais/grind
            cd grind
            bun install
            ```
          </Step>

          <Step title="Initialize your vault">
            ```bash theme={null}
            bun cli init
            ```
          </Step>

          <Step title="(Optional) Add to PATH">
            Add a shell alias for convenience:

            ```bash theme={null}
            echo 'alias grindxp="bun --cwd ~/grind cli"' >> ~/.zshrc
            source ~/.zshrc
            ```
          </Step>
        </Steps>
      </Tab>

      <Tab title="Windows (WSL2)">
        <Steps>
          <Step title="Enable WSL2">
            ```powershell theme={null}
            wsl --install
            ```

            Restart when prompted, then open a WSL terminal.
          </Step>

          <Step title="Install Bun inside WSL">
            ```bash theme={null}
            curl -fsSL https://bun.sh/install | bash
            ```
          </Step>

          <Step title="Clone and install">
            ```bash theme={null}
            git clone https://github.com/esau-morais/grind
            cd grind
            bun install
            ```
          </Step>

          <Step title="Initialize your vault">
            ```bash theme={null}
            bun cli init
            ```
          </Step>
        </Steps>

        <Warning>
          Run Grind inside WSL2, not in a native Windows shell. The Forge's filesystem watchers and process detection require a POSIX environment.
        </Warning>
      </Tab>

      <Tab title="Windows (PowerShell native)">
        Native Windows support is limited. The Forge daemon and some integrations require WSL2 or a Linux environment. For full functionality, use WSL2.

        For basic quest/XP/CLI usage only:

        <Steps>
          <Step title="Install Bun">
            ```powershell theme={null}
            powershell -c "irm bun.sh/install.ps1 | iex"
            ```
          </Step>

          <Step title="Clone and install">
            ```powershell theme={null}
            git clone https://github.com/esau-morais/grind
            cd grind
            bun install
            ```
          </Step>

          <Step title="Initialize">
            ```powershell theme={null}
            bun cli init
            ```
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

## After Installation

<CardGroup cols={2}>
  <Card title="Quickstart" icon="play" href="/docs/get-started/quickstart">
    Create your first quest and complete it.
  </Card>

  <Card title="Set up AI companion" icon="brain" href="/docs/cli/setup">
    Configure an AI provider to unlock the companion.
  </Card>

  <Card title="Configure integrations" icon="plug" href="/docs/cli/integrations">
    Connect Telegram, Discord, WhatsApp, or Google Calendar.
  </Card>

  <Card title="Launch the TUI" icon="monitor" href="/docs/tui">
    Open the 30fps terminal dashboard.
  </Card>

  <Card title="Self-host on a VPS" icon="server" href="/docs/install/self-hosting">
    Run Grind 24/7 on any VPS or server with systemd, a reverse proxy, and TLS.
  </Card>
</CardGroup>

## Updating

<CodeGroup>
  ```bash installer theme={null}
  curl -fsSL https://grindxp.app/install.sh | bash
  ```

  ```bash source theme={null}
  cd grind && git pull && bun install
  ```
</CodeGroup>

## Uninstalling

Use the built-in uninstall command for a guided experience:

```bash theme={null}
grindxp uninstall
```

This stops running services (gateway, web app) and optionally removes your vault and config. See the [uninstall command reference](/docs/cli/uninstall) for all flags including `--all`, `--dry-run`, and `--yes`.

To also remove the CLI binary after uninstalling:

<CodeGroup>
  ```bash installer theme={null}
  rm -rf ~/.grind/bin/
  ```

  ```bash bun theme={null}
  bun remove -g grindxp
  ```

  ```bash npm theme={null}
  npm uninstall -g grindxp
  ```

  ```bash pnpm theme={null}
  pnpm remove -g grindxp
  ```

  ```bash source theme={null}
  # Remove alias from ~/.zshrc or ~/.bashrc
  nano ~/.zshrc
  # Delete the line: alias grind="bun --cwd ~/grind cli"

  # Then delete the repo
  rm -rf ~/grind
  ```
</CodeGroup>

<Warning>
  Removing `~/.grind/` deletes your vault, encryption key, and all quest data. Back up
  `~/.grind/vault.db` and `~/.grind/config.json` before uninstalling if you want to preserve your
  data.
</Warning>