Metadata-Version: 2.4
Name: climash
Version: 0.1.1
Summary: Ambient terminal weather effects – snow, rain, sun, and spring leaves
Author: Climash Contributors
License: MIT License
        
        Copyright (c) 2024 Climash Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: terminal,cli,animation,weather,ascii-art,rain,snow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Dynamic: license-file

# Climash 🌨

> **Ambient terminal weather effects** – beautiful, non-intrusive animations that play in the background while you work.

[![PyPI](https://img.shields.io/pypi/v/climash)](https://pypi.org/project/climash/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## What is Climash?

Climash renders subtle weather particle effects (snow ❄, rain 🌧, sunlight ☀, spring leaves 🍂) at the **top of your terminal** using ANSI escape sequences, while leaving your shell prompt and all command output completely intact.

```
❄   ❄     ❄  ❄      ❄   ❄   ❄   ❄
  ❄    ❄         ❄      ❄       ❄
❄        ❄    ❄     ❄      ❄      ❄
user@machine:~$ ping google.com
PING google.com (142.250.80.46) 56(84) bytes of data.
64 bytes from lga34s32-in-f14.1e100.net: icmp_seq=1 ttl=115 time=12.4 ms
```

The animation runs in a **background thread** at ~12 FPS. It never clears the full screen and never overwrites your output.

---

## Installation

### Windows PowerShell

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
climash
```

If the `climash` launcher is not on your PATH yet, use:

```powershell
python -m climash.main
```

If you cloned the repo into a folder with spaces in the path, quote it:

```powershell
python -m pip install -e "D:\DUK Study\Projects-Personal\climash"
```

In PowerShell, do not use `start` by itself. That is PowerShell's built-in
`Start-Process` alias. Always call the app as `climash start`.

If PowerShell still tries to treat `start` like a shell command, use the
stop-parsing operator:

```powershell
climash --% start
```

### Linux / macOS shell

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
climash
```

If the launcher is not available, use:

```bash
python -m climash.main
```

### Install from PyPI

```bash
pip install climash
```

Or install from source on either platform:

```bash
git clone https://github.com/Vimal-Mudalagi/climash.git
cd climash
pip install -e .
```

If you want to verify the install on a fresh system, run:

```bash
climash --help
climash themes
climash start
```

If the `climash` command is not available yet, use the module form:

```bash
python -m climash.main --help
python -m climash.main themes
python -m climash.main start
```

**Requirements:** Python 3.10+ — no mandatory third-party dependencies.

---

## Quick Start

```bash
# Show banner and usage
climash

# Start with a random theme
climash start

# Start a specific theme
climash start snow
climash start rain
climash start sun
climash start spring

# Stop the animation (or just press Ctrl-C in the running terminal)
climash stop

# List all themes
climash themes
```

If the `climash` command is not available in your shell yet, run:

```bash
python -m climash.main
```

If you are in PowerShell and the launcher is missing, use:

```powershell
python -m climash.main themes
python -m climash.main start
```

---

## CLI Reference

### `climash`
Display the welcome banner and usage instructions.

```
╔════════════════════════╗
║                        ║
║        CLIMASH         ║
║   terminal weather     ║
║        vibes           ║
║                        ║
╚════════════════════════╝
```

---

### `climash start [theme]`

Start the animation.  Optional `theme` argument overrides the configured default.

```bash
climash start          # uses configured default (or random)
climash start snow
climash start rain
climash start sun
climash start spring
```

On Windows PowerShell, use `climash start` rather than `start`.

If that still opens the PowerShell `Start-Process` prompt, run:

```powershell
climash --% start
```

Press **Ctrl-C** to stop.

---

### `climash stop`

Prints guidance on stopping the animation (Ctrl-C or `kill <PID>`).

---

### `climash themes`

List all available themes:

```
Available themes:

  ❄  snow          Gently falling snowflakes
  🌧 rain          Fast falling rain drops
  ☀  sun           Warm sunlight glow particles
  🍂 spring        Drifting spring leaves
```

---

### `climash set <theme>`

Persist a default theme to `~/.climash/config.json`.

```bash
climash set snow
climash set rain
climash set sun
climash set spring
climash set random
```

---

### `climash random`

Set the default theme to `random` (a different theme is chosen each session).

```bash
climash random
```

---

### `climash disable`

Disable the automatic theme (sets default to `"none"`).

```bash
climash disable
```

---

### `climash --help`

Print full argparse help text.

---

## Themes

| Command | Particles | Movement | Colours |
|---------|-----------|----------|---------|
| `snow` | ❄ ✦ · | Downward drift | White / light blue |
| `rain` | \| . | Fast vertical drop | Blue |
| `sun` | ☀ ✧ * | Gentle flicker / glow | Yellow / gold |
| `spring` | 🍂 🍃 ✿ ❀ | Diagonal drift | Orange / green |

---

## Configuration

Climash stores a small JSON config file at `~/.climash/config.json`:

```json
{
  "default": "snow"
}
```

Possible values for `"default"`: `"snow"`, `"rain"`, `"sun"`, `"spring"`, `"random"`, `"none"`.

---

## Auto-Start

To launch Climash automatically every time you open a terminal, add the
following to your shell startup file.

**Bash** (`~/.bashrc`):

```bash
climash start &
```

**Zsh** (`~/.zshrc`):

```zsh
climash start &
```

**Fish** (`~/.config/fish/config.fish`):

```fish
climash start &
```

**PowerShell** (`$PROFILE`):

```powershell
climash start
```

On Windows, `climash start` runs in the foreground. If you want a detached
session, launch it from a separate terminal window or use a background job.

> **Tip:** `climash set snow` (or any theme) before adding to your rc file so the same theme starts each session.

---

## How It Works

1. `climash start` launches an `AnimationEngine` in a **daemon thread**.
2. The engine detects the terminal width dynamically.
3. Each frame (~12 FPS):
   - Saves the current cursor position (`ESC 7`).
   - Moves to rows 1–3 (the reserved animation region).
   - Renders updated particle positions.
   - Restores the cursor (`ESC 8`).
4. When stopped, the reserved rows are cleared and the cursor is restored.

This means **no full-screen clear**, and your shell prompt stays exactly where it is.

---

## Contributing

Contributions are welcome!  See the project structure below and open a PR.

```
climash/
├── climash/
│   ├── __init__.py    – package version
│   ├── main.py        – CLI (argparse)
│   ├── engine.py      – background animation thread
│   ├── animations.py  – particle logic & rendering
│   ├── themes.py      – theme definitions
│   └── config.py      – ~/.climash/config.json management
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore
```

---

## License

[MIT](LICENSE) © Climash Contributors
