zortify 0.1.1
AI-powered file organization CLI tool
Requires Python: >=3.10
Keywords: ai, automation, cli, file-organizer, productivity

<p align="center">
  <img src="https://raw.githubusercontent.com/zeerakzubair/zortify/68febacd8743a89cc67a16648deb2afcf4bd87ac/assets/banner.svg" alt="Zortify - AI-powered file organization" width="500">
</p>

<p align="center">
  <a href="https://github.com/zeerakzubair/zortify/actions/workflows/ci.yml"><img src="https://github.com/zeerakzubair/zortify/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://badge.fury.io/py/zortify"><img src="https://badge.fury.io/py/zortify.svg" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

<p align="center">
  A command-line tool that automatically organizes messy folders using AI-powered file classification.<br>
  Stop wasting time manually sorting your Downloads folder.
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="docs/USAGE.md">Usage Guide</a> •
  <a href="docs/CONFIGURATION.md">Configuration</a> •
  <a href="#ai-setup-optional">AI Setup</a>
</p>

## Why I Built This

My Downloads folder was a disaster - hundreds of files piled up with no organization. I got tired of manually sorting PDFs, images, installers, and random files. So I built this tool to handle it automatically.

The AI part is optional - it works great with just file extensions, but if you want smarter classification (like recognizing "Q4_Report_Final_v2.pdf" as a document even without looking at the extension), you can enable local AI with Ollama.

## Features

- **Smart Classification** - Recognizes files by extension, filename patterns, and optionally AI
- **Dry Run Mode** - Preview changes before anything moves
- **Undo Support** - Made a mistake? Just run `zortify undo`
- **Custom Rules** - Set up your own patterns (e.g., all `*invoice*` files go to Documents/Invoices)
- **Works Offline** - No internet required (AI runs locally via Ollama)
- **Cross-Platform** - Windows, macOS, Linux

## Installation

```bash
pip install zortify
```

Or install from source:

```bash
git clone https://github.com/zeerakzubair/zortify.git
cd zortify
pip install -e .
```

## Quick Start

```bash
# See what would happen (dry run)
zortify organize ~/Downloads --dry-run

# Actually organize
zortify organize ~/Downloads

# Undo if needed
zortify undo
```

## Usage

### Organize Files

```bash
# Basic usage
zortify organize ~/Downloads

# Preview without moving
zortify organize ~/Downloads --dry-run

# Include subfolders
zortify organize ~/Downloads --recursive

# Skip confirmation
zortify organize ~/Downloads --yes

# Verbose output
zortify organize ~/Downloads -v
```

### Check Folder Status

```bash
zortify status ~/Downloads
```

### Undo Operations

```bash
# Undo last operation
zortify undo

# Undo last 5 operations
zortify undo --steps 5
```

### Configuration

```bash
# Create config file
zortify config --init

# View current config
zortify config --show

# Edit config
zortify config --edit
```

## AI Setup (Optional)

The tool works without AI, but enabling it gives smarter classification.

### Option 1: Ollama (Recommended - Free & Local)

1. Install Ollama from [ollama.com](https://ollama.com/download)
2. Pull a model:
   ```bash
   ollama pull phi3
   ```
3. That's it! Zort uses Ollama by default.

### Option 2: Groq (Free Tier - Cloud)

1. Get API key from [console.groq.com](https://console.groq.com/keys)
2. Set environment variable:
   ```bash
   export GROQ_API_KEY=your_key_here
   ```
3. Update config:
   ```bash
   zortify config --edit
   # Change provider to "groq"
   ```

### Check AI Status

```bash
zortify ai
```

## Default Categories

| Category | Extensions |
|----------|------------|
| Documents | pdf, doc, docx, txt, xls, xlsx, ppt, pptx |
| Images | jpg, png, gif, webp, svg, bmp |
| Videos | mp4, mkv, avi, mov, webm |
| Audio | mp3, wav, flac, aac, ogg |
| Archives | zip, rar, 7z, tar, gz |
| Code | py, js, ts, java, cpp, go, rs |
| Installers | exe, msi, dmg, deb, rpm |
| Data | csv, json, xml, yaml, sql |

## Custom Rules

Edit `~/.config/zort/config.yaml`:

```yaml
rules:
  - pattern: "*invoice*"
    category: documents
    subfolder: Invoices

  - pattern: "screenshot*"
    category: images
    subfolder: Screenshots

  - pattern: "*.tmp"
    action: delete
```

## Documentation

For more detailed information:

- **[Usage Guide](docs/USAGE.md)** - Complete command reference, workflow examples, and tips
- **[Configuration Guide](docs/CONFIGURATION.md)** - All config options, AI provider setup, custom rules

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/
```

## Support

If this tool saved you time, consider buying me a coffee:

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow.svg)](https://buymeacoffee.com/zeerakzubair)

## License

MIT License - see [LICENSE](LICENSE) for details.

## Author

**Zeerak Zubair** - [zubairzeerak@gmail.com](mailto:zubairzeerak@gmail.com)

- GitHub: [@zeerakzubair](https://github.com/zeerakzubair)
- Buy Me a Coffee: [buymeacoffee.com/zeerakzubair](https://buymeacoffee.com/zeerakzubair)