File Explorer CLI

A Python file manager that supports:

• Standard command mode (file-explorer <command> ...)
• Interactive shell mode (file-explorer --interactive)
• Terminal GUI mode (file-explorer gui)

Designed for the Open Source Week contest and extended with safety-focused features (trash, undo, critical-path protection, graceful error handling).

---

Table of Contents

• Overview
• Features
• Project Structure
• Requirements
• Installation
• Usage
• Safety Model
• Testing
• Build & Release
• Contributing
• Security
• License

---

Overview

file-explorer is a cross-mode file management tool written in Python 3.10+.

It focuses on:

• Safe file operations with undo support
• Clear and consistent error handling
• Interactive and GUI usability for quick navigation
• Minimal external dependencies

---

Features

Required Operations

Command	Description
file-explorer folders <name1> <name2> ...	Create one or more folders
file-explorer folders <parent>,<child>	Create nested folder
file-explorer files <name1> <name2> ...	Create one or more files
file-explorer list	List directories and files
file-explorer pwd	Show current app working directory
file-explorer cd <folder>	Change app working directory
file-explorer back	Go back to previous working directory
file-explorer delete <name>	Delete file/folder (folder requires confirmation)
file-explorer rename <old> <new>	Rename file/folder
file-explorer copy <source> <destination>	Copy file
file-explorer move <source> <destination>	Move file/folder
file-explorer info <file>	Show file metadata

Extended Features

Command	Description
file-explorer search <pattern>	Search recursively by partial name
file-explorer tree [target] [--depth N]	Render folder tree
file-explorer trash <name>	Move target to trash
file-explorer trash-list	List trash items
file-explorer restore <token> [destination]	Restore trashed item
file-explorer trash-clear	Clear trash and orphan trash artifacts
file-explorer undo	Undo latest destructive action
file-explorer undo --show	Preview pending undo action
file-explorer path <name>	Print absolute path
file-explorer copypath <name>	Copy path to clipboard (with manual fallback)

Modes

• Command mode: one command per invocation
• Interactive shell mode: history, aliases, persistent state
• GUI mode: arrow-key menu navigation, status bar, bulk operations, progress output

---

Project Structure

.
├── src/file_manager_cli/
│   ├── cli.py          # parser + command dispatch
│   ├── fs_ops.py       # filesystem operations and safety checks
│   ├── shell.py        # interactive shell mode
│   ├── tui.py          # terminal GUI mode
│   ├── state.py        # persisted app state (cwd)
│   ├── output.py       # color/output helpers
│   ├── main.py         # entrypoint
│   └── __main__.py
├── tests/
│   ├── test_cli_required_commands.py
│   └── test_extras.py
├── pyproject.toml
├── README.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CHANGELOG.md
└── LICENSE

---

Requirements

• Python >=3.10
• Linux/macOS/WSL recommended
• Optional clipboard tools for copypath:
  • wl-copy (Wayland)
  • xclip or xsel (X11)

---

Installation

Local development setup

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Verify installation

file-explorer --help

---

Usage

1) Command mode

file-explorer folders docs src
file-explorer folders docs,images
file-explorer files notes.txt docs/readme.md
file-explorer list
file-explorer cd docs
file-explorer back
file-explorer cd -
file-explorer info notes.txt
file-explorer tree . --depth 2

2) Interactive shell mode

file-explorer --interactive

In shell mode:

• Use help for command overview
• Use back or cd - to return to previous directory
• Use history for recent commands
• Use alias ll list to define aliases
• Use clear to clear terminal
• Use exit to quit

3) GUI mode

file-explorer gui

In GUI mode:

• Navigate with ↑ / ↓ and Enter
• Number keys are supported as fallback
• Includes status bar (cwd, item count, free space)
• Includes bulk operations with progress output

---

Safety Model

The application is designed to fail safely:

• Destructive operations are undo-aware (delete, move, rename, trash)
• Critical paths are protected from destructive commands:
  • /
  • home directory
• Metadata writes are atomic where applicable
• Parsing and runtime errors are converted to user-friendly errors
• Unexpected exceptions are caught and returned as safe failures

---

Testing

Run full test suite:

source .venv/bin/activate
python -m pytest -q

Current suite includes:

• Required command lifecycle tests
• Undo/trash/tree behavior
• GUI and shell edge cases
• Argument parsing error paths
• Fail-safe/safe-fail regression tests

---

Build & Release

Build source and wheel distributions:

source .venv/bin/activate
python -m pip install build
python -m build

Artifacts are generated in dist/.

---

Contributing

Please read CONTRIBUTING.md before opening pull requests.

---

Security

Please read SECURITY.md for vulnerability reporting guidance.

---

License

This project is licensed under the MIT License. See LICENSE.

---

Demo Video

The recoding of the demo video results in a blnk screen in the recording. i couldnt fix the issue in time in my pc. I have provided a detailed documentation of all features please refer to it.