Installation

Requirements

macOS 12+, Linux (x86_64 / arm64), or Windows 10+ (via WSL2 or PowerShell)
Bun v1.0+ (required at runtime)

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

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.

Installer script (recommended)

The fastest path. Downloads, installs, and runs the setup wizard automatically.

curl -fsSL https://grindxp.app/install.sh | bash

iwr -useb https://grindxp.app/install.ps1 | iex

The script:

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

To skip the setup wizard:

curl -fsSL https://grindxp.app/install.sh | bash -s -- --no-init

& ([scriptblock]::Create((iwr -useb https://grindxp.app/install.ps1))) -NoInit

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

Package manager (bun / npm / pnpm)

bun install -g grindxp

npm install -g grindxp

pnpm add -g grindxp

From source

For contributors or users who want to track main.

macOS / Linux
Windows (WSL2)
Windows (PowerShell native)

Install Bun

curl -fsSL https://bun.sh/install | bash

Clone and install

git clone https://github.com/esau-morais/grind
cd grind
bun install

Initialize your vault

bun cli init

(Optional) Add to PATH

Add a shell alias for convenience:

echo 'alias grindxp="bun --cwd ~/grind cli"' >> ~/.zshrc
source ~/.zshrc

Enable WSL2

wsl --install

Restart when prompted, then open a WSL terminal.

Install Bun inside WSL

curl -fsSL https://bun.sh/install | bash

Clone and install

git clone https://github.com/esau-morais/grind
cd grind
bun install

Initialize your vault

bun cli init

Run Grind inside WSL2, not in a native Windows shell. The Forge’s filesystem watchers and process detection require a POSIX environment.

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:

Install Bun

powershell -c "irm bun.sh/install.ps1 | iex"

Clone and install

git clone https://github.com/esau-morais/grind
cd grind
bun install

Initialize

bun cli init

After Installation

Quickstart

Create your first quest and complete it.

Set up AI companion

Configure an AI provider to unlock the companion.

Configure integrations

Connect Telegram, Discord, WhatsApp, or Google Calendar.

Launch the TUI

Open the 30fps terminal dashboard.

Self-host on a VPS

Run Grind 24/7 on any VPS or server with systemd, a reverse proxy, and TLS.

Updating

curl -fsSL https://grindxp.app/install.sh | bash

cd grind && git pull && bun install

Uninstalling

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

grindxp uninstall

This stops running services (gateway, web app) and optionally removes your vault and config. See the uninstall command reference for all flags including --all, --dry-run, and --yes. To also remove the CLI binary after uninstalling:

rm -rf ~/.grind/bin/

bun remove -g grindxp

npm uninstall -g grindxp

pnpm remove -g grindxp

# Remove alias from ~/.zshrc or ~/.bashrc
nano ~/.zshrc
# Delete the line: alias grind="bun --cwd ~/grind cli"

# Then delete the repo
rm -rf ~/grind

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.

Introduction

Install

How It Works

Installation

Requirements

After Installation

Quickstart

Set up AI companion

Configure integrations

Launch the TUI

Self-host on a VPS

Updating

Uninstalling

​Requirements

​After Installation

Quickstart

Set up AI companion

Configure integrations

Launch the TUI

Self-host on a VPS

​Updating

​Uninstalling

Requirements

After Installation

Updating

Uninstalling