Play Wordle in your terminal with style
╦ ╦╔═╗╦═╗╔╦╗╦ ╔═╗
║║║║ ║╠╦╝ ║║║ ║╣
╚╩╝╚═╝╩╚══╩╝╩═╝╚═╝
A beautiful terminal-based Wordle game with shared leaderboard, streaks, and statistics.
Installation • Features • Usage • Self-Hosting • Contributing
- Daily Wordle - New word every day at 9 AM KST
- Google Login - One-click browser authentication
- Global Leaderboard - Compete with players worldwide
- Streaks & Stats - Track your winning streaks and performance
- GitHub-style Graph - Visualize your play history
- Auto-save - Resume your game anytime
- Offline Mode - Play without an account
- Beautiful TUI - Smooth animations powered by Textual
# Using pip
pip install tui-wordle
# Using uv (recommended)
uv tool install tui-wordle
# Using pipx
pipx install tui-wordle# Start the game
wordle
# Alternative commands
tui-wordle
wd| Key | Action |
|---|---|
A-Z |
Type letter |
Enter |
Submit guess |
Backspace |
Delete letter |
ESC |
Quit |
F1 |
Statistics |
F2 |
Leaderboard |
F3 |
Help |
F4 |
Settings |
tui-wordle/
├── client/ # TUI Client (Textual)
│ ├── app.py # Main application
│ ├── screens/ # Game screens
│ │ ├── game_screen.py
│ │ ├── login_screen.py
│ │ ├── result_screen.py
│ │ ├── stats_screen.py
│ │ └── ...
│ └── widgets/ # UI components
│ ├── game_board.py
│ ├── keyboard.py
│ ├── tile.py
│ └── ...
├── server/ # FastAPI Backend
│ ├── main.py
│ ├── auth/ # Authentication
│ ├── games/ # Game logic
│ ├── words/ # Daily words
│ ├── leaderboard/ # Rankings
│ ├── streaks/ # Streak tracking
│ └── stats/ # Statistics
├── admin-web/ # Admin Dashboard (Vue)
├── data/ # Word lists
├── alembic/ # DB migrations
└── scripts/ # Utility scripts
Want to run your own Wordle server? See the Self-Hosting Guide.
# Clone the repository
git clone https://github.com/subinium/tui-wordle.git
cd tui-wordle
# Install dependencies
pip install -e ".[server]"
# Set environment variables
export DATABASE_URL="postgresql+asyncpg://user:pass@localhost/wordle"
export SECRET_KEY="your-secret-key"
export GOOGLE_CLIENT_ID="your-google-client-id"
export GOOGLE_CLIENT_SECRET="your-google-client-secret"
# Run migrations
alembic upgrade head
# Seed words
python scripts/seed_database.py
# Start server
uvicorn server.main:app --reload| Variable | Description | Required |
|---|---|---|
DATABASE_URL |
PostgreSQL connection string | Yes |
SECRET_KEY |
JWT secret key | Yes |
GOOGLE_CLIENT_ID |
Google OAuth client ID | Yes |
GOOGLE_CLIENT_SECRET |
Google OAuth client secret | Yes |
ADMIN_EMAILS |
Comma-separated admin emails | No |
CORS_ORIGINS |
Allowed CORS origins | No |
| Component | Technology |
|---|---|
| TUI Client | Textual + Rich |
| Backend | FastAPI + SQLAlchemy |
| Database | PostgreSQL (via Neon) |
| Admin Dashboard | Vue 3 + Vite |
| Deployment | Railway |
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Play Now · Report Bug · Request Feature
Made with love by @subinium