Metadata-Version: 2.4
Name: filecraft-cli
Version: 1.1.0
Summary: A CLI organizer you didn’t know you needed — yet.
License-Expression: MIT
License-File: LICENSE
Keywords: cli,file-organizer,filesystem,automation,developer-tools
Author: MURTAZA PATEL
Author-email: murtazapatel89100@gmail.com
Requires-Python: >=3.10,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Filesystems
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: typer (>=0.24.1,<0.25.0)
Project-URL: Homepage, https://github.com/murtazapatel89100/Filecraft
Project-URL: Issues, https://github.com/murtazapatel89100/Filecraft/issues
Project-URL: Repository, https://github.com/murtazapatel89100/Filecraft
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/murtazapatel89100/Filecraft/main/assets/Filecraft-banner.png" width="900">
</p>

<h1 align="center">Filecraft</h1>

<p align="center">
A CLI organizer you didn’t know you needed — yet.
</p>

<p align="center">
  <a href="https://pypi.org/project/filecraft-cli/">
    <img src="https://img.shields.io/pypi/v/filecraft-cli">
  </a>
  <img src="https://img.shields.io/pypi/pyversions/filecraft-cli">
  <img src="https://img.shields.io/github/license/murtazapatel89100/Filecraft">
  <img src="https://img.shields.io/pypi/dm/filecraft-cli">
</p>

This is the Python implementation of Filecraft, focused on safe and repeatable file organization workflows.

## Demo

Watch Filecraft in action:

https://github.com/murtazapatel89100/Filecraft/blob/main/assets/demo-video.mp4

## Requirements

- Python `>=3.10,<3.15`

## Distribution

- Package target: PyPI (`filecraft-cli`)
- CLI command: `filecraft`
- Standalone binary: `Filecraft` (PyInstaller)

## Install / Run

### Option 1: Local development (Poetry)

```bash
poetry install
poetry run filecraft --help
```

### Option 2: PyPI install (release users)

```bash
pip install filecraft-cli
filecraft --help
```

### Option 2: Run module directly (without installing script)

```bash
PYTHONPATH=src python -m file_organiser_python.main --help
```

## Commands

- `filecraft rename`
- `filecraft separate`
- `filecraft merge`
- `filecraft revert`

All commands support `--dry-run` to preview actions without moving files.
Working directory flags are validated before any `--target-dir` creation prompt.

## `rename`

Renames files in `working_dir` and moves them to `target_dir`.
By default names are numeric (`1.ext`, `2.ext`, ...); with `--rename-with` they become prefixed (`name_1.ext`, `name_2.ext`, ...).

### Options

- `--working-dir PATH` (default: current directory)
- `--target-dir PATH` (default: current directory)
- `--recursive` (include files from subdirectories at unlimited depth)
- `--dry-run`
- `--history` (save history file for revert)
- `--rename-with TEXT` (optional base name prefix, e.g. `invoice`)

If `--target-dir` is provided and does not exist, the CLI prompts to create it (`y/n`).
Declining exits with a `--target-dir` error.

### Rename Example

```bash
filecraft rename --working-dir ./downloads --target-dir ./renamed --history
filecraft rename --working-dir ./downloads --target-dir ./renamed --rename-with invoice
```

## `separate`

Separates files according to mode.

### Separate Modes

- `extension`: Move files of a specific extension (e.g. `.pdf`) into `TARGET/PDF`
- `date`: Move files modified on a specific date (or today) into `TARGET/YYYY-MM-DD`
- `extension_and_date`: Combine both filters into `TARGET/YYYY-MM-DD/EXT`
- `file`: Sort all files by file type category (`IMAGES`, `VIDEOS`, `DOCUMENTS`, `ARCHIVES`, etc.)

### Separate Options

- `--mode [extension|date|extension_and_date|file]` (default: `extension`)
- `--extension TEXT` (required for `extension` and `extension_and_date`)
- `--file-type TEXT` (optional for `file`; accepts category like `documents` or extension like `pdf`)
- `--date YYYY-MM-DD` (used by `date` and `extension_and_date`; validated)
- `--working-dir PATH` (default: current directory)
- `--target-dir PATH` (default: current directory)
- `--recursive` (include files from subdirectories at unlimited depth)
- `--dry-run`
- `--history`

### Separate Examples

```bash
filecraft separate --mode extension --extension pdf --working-dir ./in --target-dir ./out
filecraft separate --mode date --date 2026-03-01 --working-dir ./in --target-dir ./out
filecraft separate --mode extension_and_date --extension .jpg --date 2026-03-01 --working-dir ./in --target-dir ./out
filecraft separate --mode file --working-dir ./in --target-dir ./out
filecraft separate --mode file --file-type pdf --working-dir ./in --target-dir ./out
```

## `revert`

Reverts moves using a history file.

### Revert Options

- `--directory PATH` (searches latest history in that directory; default: current directory)
- `--history-file PATH` (use a specific history file)
- `--dry-run`
- `--keep-history` (do not delete history file after successful revert)

### Revert Examples

```bash
filecraft revert --directory ./out
filecraft revert --history-file ./out/.organizer_history_2026-03-01_12-00-00-123456.json
```

## `merge`

Merges files from multiple `working_dir` locations into a single `target_dir`.

### Merge Modes

- `extension`: Merge files of a specific extension into `TARGET/EXT`
- `date`: Merge files modified on a specific date (or today) into `TARGET/YYYY-MM-DD`
- `extension_and_date`: Combine both filters into `TARGET/YYYY-MM-DD/EXT`
- `file`: Merge all files by file type category (`IMAGES`, `VIDEOS`, `DOCUMENTS`, `ARCHIVES`, etc.)

### Merge Options

- `--mode [extension|date|extension_and_date|file]` (default: `extension`)
- `--extension TEXT` (required for `extension` and `extension_and_date`)
- `--date YYYY-MM-DD` (used by `date` and `extension_and_date`; validated)
- `--working-dir PATH` (required, repeat for multiple source directories)
- `--target-dir PATH` (default: current directory)
- `--recursive` (include files from subdirectories at unlimited depth)
- `--dry-run`
- `--history`

When `--recursive` is set and multiple `--working-dir` flags are provided, Filecraft traverses all listed working directories recursively.

### Merge Examples

```bash
filecraft merge --mode extension --extension pdf --working-dir ./downloads --working-dir ./desktop --target-dir ./merged
filecraft merge --mode date --date 2026-03-01 --working-dir ./in1 --working-dir ./in2 --target-dir ./merged
filecraft merge --mode extension_and_date --extension .jpg --date 2026-03-01 --working-dir ./camera --working-dir ./phone --target-dir ./merged
filecraft merge --mode file --working-dir ./in1 --working-dir ./in2 --target-dir ./merged
```

## Notes

- History files are saved with a timestamped name like `.organizer_history_YYYY-MM-DD_HH-MM-SS-ffffff.json`.
- File collisions are handled safely by appending suffixes like `_1`, `_2`, etc.
- Compound extensions such as `.tar.gz` are recognized when sorting by file type.

