Skip to main content

​
Prerequisites

  • Bun v1.0+. Grind runs on Bun, not Node.
  • A terminal.

​
Install

1

Run the installer (recommended)

For other installation methods (npm, yarn, pnpm, or from source), see Installation.
2

Initialize your vault

This runs the setup wizard. It will:
  • Create ~/.grind/ (your config and vault directory)
  • Generate an encryption key for your SQLite vault
  • Create your user profile (name, timezone)
  • Run database migrations
You can skip AI setup for now. Grind works fully without an API key. Add one later with grindxp setup.
3

Check your status

You should see your character’s level, XP, and an empty quest log.
4

Create your first quest

The interactive wizard will ask for:
  • Title: what you’re doing
  • Type: daily, weekly, bounty, epic, chain, or ritual
  • Difficulty: easy, medium, hard, or epic
  • Skills: which skill tags this quest contributes to
5

Complete it

Select your quest and self-report completion. You’ll see XP awarded and skill progress updated.

​
Next Steps

Open the TUI

Launch the terminal dashboard for a real-time view of your quests, skills, and XP. bash bun tui

Set up your AI companion

Configure an AI provider to unlock the companion and agent features. bash grindxp setup

Start timer tracking

Use start and stop to get a 1.5x XP proof bonus for timed work.

Automate with the Forge

Create rules that watch your git activity, filesystem, or webhooks.

​
Environment Variables

Grind reads configuration from ~/.grind/config and environment variables. Copy .env.example to .env for development:
Key variables: See Environment Reference for the full list.