Skip to main content

​
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)

bun install -g grindxp
For contributors or users who want to track main.
1

Install Bun

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

Clone and install

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

Initialize your vault

bun cli init
4

(Optional) Add to PATH

Add a shell alias for convenience:
echo 'alias grindxp="bun --cwd ~/grind cli"' >> ~/.zshrc
source ~/.zshrc

​
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

​
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/
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.