soracli 1.0.0

Real-time terminal ambient environment engine that synchronizes real-world weather conditions with animated terminal simulations

SoraCLI 🌦️

SoraCLI is a terminal weather simulation tool that displays animated ASCII weather (rain, snow, thunderstorms, fog) in your terminal. It can sync with real-world weather data or run in demo mode.

┌────────────────────────────────────────────────────────────────┐
│  ┃   │   ┃        │   ┃   │   ┃        │   ┃   │   ┃          │
│    │   ┃        │   ┃   │   ┃        │   ┃   │   ┃   │        │
│  ┃   │   ┃   │   ┃   │   ┃   │   ┃   │   ┃   │   ┃   │        │
│  ·  ° · °  ·  °  · ° · ° · °  ·  °  · ° · °                    │
└────────────────────────────────────────────────────────────────┘

Installation

Option 1: Install from source

git clone https://github.com/yourusername/SoraCLI.git
cd SoraCLI
pip install .

Option 2: Development mode

git clone https://github.com/yourusername/SoraCLI.git
cd SoraCLI
pip install -e .

Verify installation

soracli --version
soracli --help

Note: If soracli command is not found, use python -m soracli instead, or add ~/.local/bin to your PATH.

Quick Start

Demo Mode (No API key needed!)

# Rain
soracli demo --rain

# Snow
soracli demo --snow

# Thunderstorm with lightning
soracli demo --storm

# Fog/mist
soracli demo --fog

# Clear night sky (twinkling stars)
soracli demo --clear --night

# With custom theme and intensity
soracli demo --rain --theme cyberpunk --intensity 1.5

# Run for specific duration (30 seconds)
soracli demo --rain --duration 30

Press Ctrl+C to exit any animation.

Live Weather Mode (Requires free API key)

1. Get a free API key from OpenWeatherMap

2. Set your API key:

   # Linux/macOS
   export OPENWEATHERMAP_API_KEY="your_api_key_here"
   
   # Windows PowerShell
   $env:OPENWEATHERMAP_API_KEY = "your_api_key_here"
   
   # Windows CMD
   set OPENWEATHERMAP_API_KEY=your_api_key_here
   

3. Start live weather:

   soracli start --location "Tokyo"
   soracli start --location "New York" --theme minimal
   

Daemon Mode (Background Weather Bar)

Run a persistent weather animation bar at the top of your terminal using tmux.

Requirements

# Ubuntu/Debian
sudo apt install tmux

# macOS
brew install tmux

# Arch Linux
sudo pacman -S tmux

Usage

# Start daemon (5-line weather bar at top)
soracli daemon start

# Start with larger panel
soracli daemon start --panel-size 10

# Check status
soracli daemon status

# Attach to see the split view
soracli daemon attach

# Detach: Press Ctrl+B, then D

# Stop daemon
soracli daemon stop

Layout

┌────────────────────────────────────────────┐
│ │╿|┃╿||│⸽╽╿ (rain animation)              │  ← 5 lines
├────────────────────────────────────────────┤
│ $ your normal shell                        │
│ $ commands work as usual                   │  ← Rest of terminal
└────────────────────────────────────────────┘

All Commands

Command	Description
soracli demo --rain	Rain simulation
soracli demo --snow	Snow simulation
soracli demo --storm	Thunderstorm with lightning
soracli demo --fog	Fog/mist effect
soracli demo --clear --night	Stars at night
soracli start -l "City"	Live weather for location
soracli init	Interactive configuration
soracli status	Show current config
soracli themes	List themes
soracli daemon start	Start background mode
soracli daemon stop	Stop background mode

Options

Demo Options

soracli demo --rain \
  --theme cyberpunk \     # default, cyberpunk, minimal, nature
  --intensity 1.5 \       # 0.1 to 2.0
  --duration 60           # seconds (0 = infinite)

Daemon Options

soracli daemon start \
  --panel-size 8 \        # Height in lines (default: 5)
  --theme cyberpunk       # Visual theme

Themes

• default - Classic terminal colors
• cyberpunk - Neon cyan/magenta
• minimal - Subtle, clean
• nature - Earthy greens

Custom Theme

Create ~/.soracli/themes/mytheme.json:

{
  "name": "mytheme",
  "rain_colors": ["cyan", "blue", "white"],
  "snow_colors": ["white", "bright_white"],
  "lightning_color": "bright_yellow"
}

Troubleshooting

"soracli: command not found"

# Use python -m instead
python -m soracli demo --rain

# Or add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"No API key found"

Use demo mode (no key needed) or set the environment variable.

Daemon issues

tmux kill-server        # Kill stuck sessions
soracli daemon start    # Start fresh

Development

pip install -e ".[dev]"
pytest                  # Run tests
pytest --cov=soracli    # With coverage

Requirements

• Python 3.8+
• click, requests, pyyaml
• tmux (daemon mode only)

License

MIT License

---

Enjoy your ambient terminal weather! 🌧️❄️⚡🌫️✨