Requirements

• Python 3.13+
• Poetry or pip package manager
• An OpenWeatherMap API key
• UTF-8 terminal with 256 colors and nerd font

Installation

Installing starlit is quick and easy. The built-in setup command guides you through configuration.

Option 1: Install with pipx

The easiest way to install starlit is via pipx:

pipx install starlit-cli

Then set up your configuration:

starlit --setup # creates ~/.config/starlit/.env
starlit --edit  # opens .env file (add your api key here) 

To upgrade to the latest version:

pipx upgrade starlit-cli

Option 2: Install from source

For local development or contributing:

1. Clone this repository

git clone https://github.com/ashuhlee/starlit.git
cd starlit

2. Create the virtual environment

# macOS / Linux / Windows
python -m venv .venv

Activate the virtual environment:

source .venv/bin/activate # macOS / Linux
.venv\Scripts\Activate    # Windows (Powershell)

3. Install in editable mode

Some packages are required for this project. They will automatically be installed if you run:

pip install -e .

4. Set up your configuration

Generates a configuration file from the example template and open the file:

starlit --setup
starlit --edit

To update your installation:

git pull origin main
pip install -e .

Get your OpenWeatherMap API key and paste it into the .env file under API_KEY=

Configuration

starlit creates a default configuration file when you run starlit --setup. The .env file stores your API key, default city and display preferences.

• Linux/macOS: ~/.config/starlit/.env
• Windows: C:\users\username\.config\starlit\.env

Customize colors

You can also set your own colors for the gradient title and message labels. Use six-digit RGB hex codes (no # needed):

Setting	Description	Example
COLOR_1	Gradient color stop 1	5D63FF
COLOR_2	Gradient color stop 2	F7A4F4
LABEL_COLOR	Message label color	5CE7F9

Usage

# basic usage
starlit

# specify city via command line
starlit seattle

# start interactive mode
starlit --interactive 

# opens the .env file in your default editor
starlit --edit

# shows config in .env file (if found)
starlit --config

# shows contents of .env file (if found)
starlit --config --show-full

# show version
starlit --version

# show help
starlit --help

Usage examples

What's next

• Different Modes: Add live updates or full forecast modes
• Interactive Mode+: Add a full command line interface when using starlit -i
• Color Themes: Support for .json theme files so you can easily switch between color palettes
• Multi-language Support: Option to view weather info in different languages

Tech stack

• Rich - Beautiful terminal formatting
• rich-gradient - Gradient text formatting
• terminal-text-effects - Smooth text animations
• Requests - HTTP requests for weather API
• Python-dotenv - Environment variable management

About this project

I built this fun little project as a way to learn more about APIs and creating colorful terminal apps. It grew into a CLI project I'm proud of!

Thank you to charm for the color palette and design interface inspo 🎨 and to wego for the ASCII icons

⭐ If you like this project, please consider giving it a star!