Metadata-Version: 2.4
Name: nekowall
Version: 2.1.2
Summary: Random anime wallpaper changer powered by Nekosia API
Author: tommy437
Keywords: wallpaper,anime,nekosia,cli,windows,macos,linux,catgirl
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# NEKOWALL

```
  ███╗   ██╗███████╗██╗  ██╗ ██████╗ ██╗    ██╗ █████╗ ██╗     ██╗
  ████╗  ██║██╔════╝██║ ██╔╝██╔═══██╗██║    ██║██╔══██╗██║     ██║
  ██╔██╗ ██║█████╗  █████╔╝ ██║   ██║██║ █╗ ██║███████║██║     ██║
  ██║╚██╗██║██╔══╝  ██╔═██╗ ██║   ██║██║███╗██║██╔══██║██║     ██║
  ██║ ╚████║███████╗██║  ██╗╚██████╔╝╚███╔███╔╝██║  ██║███████╗███████╗
  ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝ ╚═════╝  ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚══════╝
```

**Random anime wallpaper changer powered by the [Nekosia API](https://nekosia.cat).**

Cross-platform: Windows, macOS, Linux (GNOME, KDE, XFCE, MATE, Cinnamon, feh, sway, hyprland).
No external dependencies — pure Python 3.8+ standard library.

***

## Installation

```bash
pip install nekowall
```

That's it. The `nekowall` command is available immediately in any terminal.

***

## Usage

```
nekowall                        random category, random image
nekowall -c catgirl             force a specific category
nekowall -c maid --keep         keep the downloaded image file permanently
nekowall --list                show all available categories with commands
nekowall --no-banner           skip the ASCII banner
nekowall --version             show version and exit
nekowall -h                    full help
```

### Examples

```bash
# Set a random wallpaper from a random category
nekowall

# Always pick from the foxgirl category
nekowall -c foxgirl

# Pick a random one but save the image to keep it
nekowall --keep

# See every available category and the exact command to use it
nekowall --list
```

***

## How it works

1. **Loads categories** — starts with 80+ hardcoded categories from the
   [Nekosia documentation](https://nekosia.cat/documentation) and the Booru tag list,
   then fetches live tags from the API and merges any new ones with `count >= 15`.
2. **Picks a random category** (or uses the one you specified with `-c`).
3. **Fetches a random image** from `GET /api/v1/images/{category}`.
4. **Downloads the image** to `$TEMP/nekowall_{id}.{ext}` with a live progress bar.
5. **Sets the wallpaper** — Windows uses `SystemParametersInfoW` (no admin), macOS uses `osascript`, Linux uses desktop-specific tools.

***

## Available categories

The full list is always up to date — run `nekowall --list` to see everything.
A non-exhaustive sample:

| Group          | Categories                                                                  |
|---------------|----------------------------------------------------------------------------|
| Animal girls  | `catgirl` `foxgirl` `wolf-girl` `wolfgirl` `doggirl` `animal-ears`          |
| Clothes       | `maid` `maid-uniform` `uniform` `sailor-uniform` `hoodie` `gym-uniform`     |
| Accessories  | `ribbon` `headphones` `thigh-high-socks` `knee-high-socks` `white-tights`   |
| Hair         | `white-hair` `blue-hair` `pink-hair` `long-hair` `twintails` `blonde`       |
| Eyes         | `blue-eyes` `red-eyes` `purple-eyes` `heterochromia` `green-eyes`           |
| Poses & vibes| `wink` `w-sitting` `lying-down` `cute` `vtuber` `blue-archive` `hololive`   |
| Seasonal     | `valentine` `halloween` `winter` `summer` `sakura`                          |

***

## Requirements

- Python 3.8 or higher
- A supported desktop environment: Windows, macOS, GNOME, KDE, XFCE, MATE, Cinnamon, feh, sway, hyprland
- Internet connection

***

## Tip: run on startup

To get a new wallpaper every time you log in:

**Windows:**
1. Press `Win + R`, type `shell:startup`, press Enter
2. Create a shortcut to `nekowall.bat` (or `nekowall`) in that folder

**macOS:**
```bash
# Create a LaunchAgent
mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.nekowall.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key><string>com.nekowall</string>
    <key>ProgramArguments</key><array><string>/usr/local/bin/nekowall</string></array>
    <key>RunAtLoad</key><true/>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/com.nekowall.plist
```

**Linux (GNOME):**
```bash
gnome-session-properties
```
Add a new entry pointing to `nekowall`.

***

## API credit

Images are provided by the **[Nekosia API](https://nekosia.cat)** — a free, public anime image API
with safety filters. No API key required.

***
