Metadata-Version: 2.4
Name: soracli
Version: 1.0.0
Summary: Real-time terminal ambient environment engine that synchronizes real-world weather conditions with animated terminal simulations
Author: SoraCLI Contributors
Maintainer: SoraCLI Contributors
License: MIT
Project-URL: Homepage, https://github.com/soracli/soracli
Project-URL: Documentation, https://github.com/soracli/soracli#readme
Project-URL: Repository, https://github.com/soracli/soracli.git
Project-URL: Issues, https://github.com/soracli/soracli/issues
Project-URL: Changelog, https://github.com/soracli/soracli/releases
Keywords: cli,terminal,weather,animation,ascii,ambient,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Terminals
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: async
Requires-Dist: aiohttp>=3.8.0; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: soracli[async,dev]; extra == "all"
Dynamic: license-file

# 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!** 🌧️❄️⚡🌫️✨
