Skip to main content

​
Overview

The GDrive Ingest script (gdrive_ingest.sh) is an ultimate cloud ingestor for Google Drive that handles downloading, extracting, organizing, and uploading files with an interactive terminal UI. It excels at music organization with metadata-based folder structures and includes comprehensive support for Telegram downloads.

​
Key Features

Interactive Folder Selection

Navigate your Google Drive folders with arrow keys - no need to remember folder IDs or names

Live Progress Tracking

Real-time download and upload progress bars with percentage indicators and file size tracking

Smart Music Organization

Automatically organizes music by Artist/Album(Year) structure using ID3 tags and metadata

Telegram Support

Download files from Telegram channels and groups using Telethon API integration

ZIP Extraction

Auto-detects ZIP files and prompts for extraction with smart folder organization

Cover Art Extraction

Automatically extracts and uploads album cover art from music files

Duplicate Detection

Checks for existing files before uploading to prevent duplicates

MD5 Checksums

Generates and displays MD5 checksums for downloaded files

​
Quick Start

​
Basic Usage

# Interactive mode - browse folders with arrow keys
./gdrive_ingest.sh https://example.com/song.mp3

# Skip folder selection by specifying destination
./gdrive_ingest.sh --folder "Music" https://example.com/song.mp3

# Multiple files
./gdrive_ingest.sh --folder "Archive" url1.mp3 url2.zip url3.mp4

​
Interactive Folder Navigation

When run without --folder, an interactive browser opens:
  • ↑/↓ - Navigate folders
  • → - Open/enter folder
  • ← - Go back to parent
  • Enter - Select folder
  • q - Quit

​
Command Line Options

​
-h, --help
flag
Show help message with detailed usage information
​
-d, --debug
flag
Debug mode (dry-run) - shows commands without executing uploads
​
-f, --folder
string
Destination folder name or ID - skips interactive folder selection
./gdrive_ingest.sh --folder "bckups" url1.mp3
​
-j, --json
file
Load URLs from a JSON file containing an array of URLs
./gdrive_ingest.sh --folder "Archive" --json downloads.json

​
URL Formats

The script accepts multiple URL input formats: 
./gdrive_ingest.sh https://example.com/file.mp3

​
Configuration

​
Environment Setup

The script requires a .env file in the same directory with your Google Drive API credentials:
.env
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
REFRESH_TOKEN="your-refresh-token"
Copy .env.example to .env and fill in your Google Drive API credentials. See the GDrive Setup guide for details.

​
Telegram Setup (Optional)

For Telegram downloads, you need:
  1. Install Telethon: pip install telethon
  2. Get API credentials from https://my.telegram.org
  3. Set environment variables:
export TELEGRAM_API_ID='your_api_id'
export TELEGRAM_API_HASH='your_api_hash'
See the Telegram Setup guide for detailed instructions on obtaining and configuring Telegram API credentials.

​
Smart File Organization

The script automatically categorizes and organizes files:

​
Music Files

Music files are organized using metadata tags: 
Music/
  ├── Artist Name/
  │   ├── Album Name (2024)/
  │   │   ├── cover.jpg
  │   │   ├── 01 - Track Name.mp3
  │   │   └── 02 - Track Name.mp3
  │   └── Single Track.mp3
  • Reads ID3 tags using ffprobe
  • Cleans up website tags and formatting
  • Creates Artist/Album(Year) folder structure
  • Extracts and uploads cover art automatically
  • Prompts before uploading to existing album folders
  • Falls back to artist folder if album is unknown

​
Other File Types

Non-music files are organized by category:
  • Images → Images/
  • Videos → Videos/
  • Documents/PDFs → Docs/
  • ZIP files → Folders/zipname/ (when extracted)
  • Others → Others/

​
ZIP File Handling

When a ZIP file is detected:
  1. The script prompts: “Extract and upload files? (y/n)”
  2. If yes: Extracts contents and uploads to Folders/zipname/
  3. If no: Uploads the ZIP file as-is to the appropriate category
Example
$ ./gdrive_ingest.sh archive.zip
📦 ZIP detected
Extract and upload files? (y/n): y
Extracting...
✓ Extracted
Organizing and uploading files...

​
Progress Display

The script provides rich, color-coded output: 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[1/3] Processing: https://example.com/song.mp3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⬇  [===========================>------] 82%
🔐 MD5: a1b2c3d4e5f6...

📀 Artist Name - Album Name (2024) - Track Title
   ⬆  Uploading 4.52MB... 100% ⠋
   ✓ Uploaded 4.52MB
   🖼  Uploading 0.12MB... 100% ⠋
   ✓ Uploaded 0.12MB

​
Duplicate Detection

Before uploading, the script checks if files already exist in the destination folder:
  • Queries Google Drive API by filename and parent folder
  • Skips files that already exist
  • Displays ”⊘ Already exists, skipping” message

​
Token Caching

Access tokens are cached in ~/.gdrive_token and automatically refreshed when expired: 
✓ Using cached access token (valid until Mon Mar 3 15:30:45 2026)

​
Requirements

The script requires the following system dependencies:
  • curl - For API requests and downloads
  • jq - JSON parsing
  • unzip - ZIP extraction
  • file - MIME type detection

​
Error Handling

​
Missing Credentials

✗ .env file not found
Create one from .env.example:
  cp .env.example .env
  # Then edit .env with your credentials

​
API Errors

If an API request fails, the script displays detailed error information: 
✗ Upload failed
API Error: The user has exceeded their storage quota
Curl exit code: 0

​
Telegram Errors

✗ Telethon library required for Telegram downloads
  Install: pip install telethon
  See: https://docs.telethon.dev/en/stable/basic/installation.html
For detailed configuration and setup:

GDrive Setup

Set up Google Drive API credentials

Telegram Setup

Configure Telegram downloads

File Organization

Learn about folder structure and organization

Interactive Features

Understand the interactive UI