soracli 1.0.0
Real-time terminal ambient environment engine that synchronizes real-world weather conditions with animated terminal simulations
License: MIT
Requires Python: >=3.8
Keywords: cli, terminal, weather, animation, ascii, ambient, simulation

# SoraCLI 🌦️

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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

```bash
git clone https://github.com/yourusername/SoraCLI.git
cd SoraCLI
pip install .
```

### Option 2: Development mode

```bash
git clone https://github.com/yourusername/SoraCLI.git
cd SoraCLI
pip install -e .
```

### Verify installation

```bash
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!)

```bash
# 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](https://openweathermap.org/api)

2. **Set your API key:**
   ```bash
   # 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:**
   ```bash
   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

```bash
# Ubuntu/Debian
sudo apt install tmux

# macOS
brew install tmux

# Arch Linux
sudo pacman -S tmux
```

### Usage

```bash
# 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

```bash
soracli demo --rain \
  --theme cyberpunk \     # default, cyberpunk, minimal, nature
  --intensity 1.5 \       # 0.1 to 2.0
  --duration 60           # seconds (0 = infinite)
```

### Daemon Options

```bash
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`:

```json
{
  "name": "mytheme",
  "rain_colors": ["cyan", "blue", "white"],
  "snow_colors": ["white", "bright_white"],
  "lightning_color": "bright_yellow"
}
```

## Troubleshooting

### "soracli: command not found"

```bash
# 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

```bash
tmux kill-server        # Kill stuck sessions
soracli daemon start    # Start fresh
```

## Development

```bash
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!** 🌧️❄️⚡🌫️✨