Skip to main content

​
Prerequisites

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

​
Install

1

Run the installer (recommended)

curl -fsSL https://grindxp.app/install.sh | bash
For other installation methods (npm, yarn, pnpm, or from source), see Installation.
2

Initialize your vault

grindxp init
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

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

Create your first quest

grindxp quest create
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

grindxp complete
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: 
cp .env.example .env
Key variables:
VariableDescription
GRIND_VAULT_PATHPath to your vault directory (default: ~/.grind)
GRIND_ENCRYPTION_KEYAES key for vault encryption (generated on init)
ANTHROPIC_API_KEYAnthropic API key for the companion
OPENAI_API_KEYOpenAI API key (alternative)
GOOGLE_GENERATIVE_AI_API_KEYGoogle Gemini API key (alternative)
OLLAMA_BASE_URLOllama endpoint for local models
See Environment Reference for the full list.