eh-gdrive-uploader 1.1.1
Cross-platform Google Drive file uploader and downloader CLI
License: MIT
Requires Python: >=3.8
Keywords: google-drive, upload, download, cli, backup, cloud-storage

# EH Google Drive Uploader

[![PyPI version](https://badge.fury.io/py/eh-gdrive-uploader.svg)](https://pypi.org/project/eh-gdrive-uploader/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Cross-platform Python CLI tool to upload and download files to/from Google Drive.

By **Esmail Ebrahim Hamza** ([@EsmailEbrahim](https://github.com/EsmailEbrahim))

## Features

- Upload any file type (including large ZIP archives)
- OAuth2 secure authentication (browser login once, reuse token)
- Upload to specific Drive folders
- Download files by ID
- Search files by name
- Rename files on upload
- Cross-platform: Windows, Linux, macOS
- Resumable uploads for reliability

## Installation

### From PyPI (Recommended)
```bash
pip install eh-gdrive-uploader
eh-gdrive-uploader --version
```

### From Source
```bash
git clone https://github.com/EsmailEbrahim/eh-gdrive-uploader.git
cd eh-gdrive-uploader
pip install -e .
```

## Usage

```bash
# Upload file
eh-gdrive-uploader myfile.zip

# Upload to folder
eh-gdrive-uploader myfile.zip -f FOLDER_ID

# Rename
eh-gdrive-uploader myfile.zip -n newname.zip

# Download
eh-gdrive-uploader -d FILE_ID
eh-gdrive-uploader -d FILE_ID -o ./downloads/

# List files
eh-gdrive-uploader --list            # or -l

# Search files
eh-gdrive-uploader --search "doc"    # or -s

# Version info
eh-gdrive-uploader --version         # or -v

# Setup help
eh-gdrive-uploader --setup
```

---

## Quick Start

### 1. Clone & Setup Environment
#### From Source (Development)

```bash
# Clone repo
git clone https://github.com/EsmailEbrahim/eh-gdrive-uploader.git
cd eh-gdrive-uploader

# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate
# Activate (Linux/macOS)
# source venv/bin/activate

# Install in editable mode
pip install -e .

# Verify installation
eh-gdrive-uploader --version
```

### 2. Google Cloud Setup (One-time)

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create new project (top-left dropdown)
3. **Enable Google Drive API:**
   - Navigation menu → APIs & Services → Library
   - Search "Google Drive API" → Click **Enable**
4. **Create OAuth Credentials:**
   - APIs & Services → Credentials
   - Click **Create Credentials** → OAuth client ID
   - Application type: **Desktop application**
   - Name: `Drive Uploader`
   - Click **Create** → **Download JSON**
5. **Place credentials:**
   - Copy downloaded file to: `~/.gdrive_uploader/credentials.json`
   - Windows: `C:\Users\YOURNAME\.gdrive_uploader\credentials.json`
   - Ubuntu: `/home/YOURNAME/.gdrive_uploader/credentials.json`

Or run: `python -m eh_gdrive_uploader.gdrive_upload --setup` for detailed instructions.

### 3. First Run (Authentication)

```bash
python -m eh_gdrive_uploader.gdrive_upload myfile.zip
```
Browser will open for Google login → Authorization token saved automatically.

---

## Error: "Access blocked: Test has not completed the Google verification process"

**Solution:**
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Select your project → **APIs & Services** → **OAuth consent screen**
3. Under **Test users**, click **Add users**
4. Add your Gmail address (`YOUREMAIL@gmail.com`)
5. Save and retry the script

---

## Usage

### Basic Upload
```bash
# Upload to Drive root
python -m eh_gdrive_uploader.gdrive_upload backup.zip

# Upload with progress
python -m eh_gdrive_uploader.gdrive_upload "C:\Users\Me\Documents\archive.zip"
```

### Upload to Specific Folder
```bash
# Get folder ID from Drive URL (last part after /folders/)
python -m eh_gdrive_uploader.gdrive_upload backup.zip -f 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
```

### Download from Google Drive
```bash
# Download file by ID (saves to current directory with original name)
eh-gdrive-uploader -d FILE_ID

# Download to specific directory (creates if doesn't exist)
eh-gdrive-uploader -d FILE_ID -o ./downloads/

# Download with new name
eh-gdrive-uploader -d FILE_ID -o myfile.zip

# Get file ID from list or URL (https://drive.google.com/file/d/FILE_ID/view)
```
> Note: Google Docs, Sheets, and Slides are automatically exported to Microsoft Office formats (.docx, .xlsx, .pptx).

### Search Files

```bash
# Search files by name
eh-gdrive-uploader --search "report"

# Search with partial match
eh-gdrive-uploader -s "backup"
```

### Rename on Upload
```bash
python -m eh_gdrive_uploader.gdrive_upload backup.zip -n "backup-2026-02-05.zip"
```

### List Recent Files
```bash
python -m eh_gdrive_uploader.gdrive_upload --list
```

### Show Setup Help
```bash
python -m eh_gdrive_uploader.gdrive_upload --setup
```

---

## Environment Management

**Activate environment (Windows):**
```powershell
venv\Scripts\activate
```

**Activate environment (Ubuntu/Linux):**
```bash
source venv/bin/activate
```

**Deactivate (any platform):**
```bash
deactivate
```

---

## Project Structure

```
eh-gdrive-uploader/
├── eh_gdrive_uploader/   # Main package
│   ├── __init__.py       # Package initializer
│   └── gdrive_upload.py  # Main script (CLI entry point)
├── venv/                 # Virtual environment (not in git)
├── .gitignore            # Ignore credentials & cache
├── CHANGELOG.md          # Project changelog
├── LICENSE               # Licens file (MIT)
├── Makefile              # Make commands for setup
├── pyproject.toml        # Python project metadata
├── README.md             # This file
├── requirements.txt      # Python dependencies
└── requirements-dev.txt  # Development dependencies
```

## Version History

See [CHANGELOG.md](CHANGELOG.md) for details.

## Security Notes

- **Never commit `credentials.json` or `token.pickle`** — they are in `.gitignore`
- Tokens stored locally in `~/.gdrive_uploader/` (user home directory)
- First run requires browser authentication; subsequent runs use saved token

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `credentials.json not found` | Run setup step 2, check file is in `~/.gdrive_uploader/` |
| Browser doesn't open | Check default browser; use same machine with GUI |
| `ModuleNotFoundError` | Run `pip install -r requirements.txt` inside venv |
| Token expired | Delete `~/.gdrive_uploader/token.pickle` and re-run |

## Author

**Esmail Ebrahim Hamza**  
- [esmailebraheem771@gmail.com](mailto:esmailebraheem771@gmail.com)
- [GitHub: EsmailEbrahim](https://github.com/EsmailEbrahim)

## License

MIT License - Free for personal and commercial use.
See [LICENSE](LICENSE) for details.