Skip to main content

​
Quick Start

1

Navigate to script directory

cd ~/workspace/source/cloud/gdrive-ingest
2

Create configuration file

cp .env.example .env
3

Edit configuration

nano .env
Add your Google Drive credentials (see Google Drive API Setup).
4

Test the script

./gdrive_ingest.sh --help

​
Installing Dependencies

​
Core Dependencies (Required)

These are required for basic functionality: 
sudo apt update
sudo apt install bash curl jq file coreutils unzip ffmpeg
What each dependency does:
PackagePurposeRequired
bash 4.0+Script runtimeYes
curlDownloads and API requestsYes
jqJSON parsingYes
fileFile type detectionYes
md5sumDuplicate detectionYes
unzipZIP extractionYes
ffprobeMusic metadata extractionFor music features
ffmpegCover art extractionFor music features

​
Optional Dependencies

Only needed if downloading from Telegram channels.Requirements:
  • Python 3.7+
  • Telethon library
Installation:
# Install Python (if not already installed)
# Ubuntu/Debian
sudo apt install python3 python3-pip

# macOS (usually pre-installed)
brew install python3

# Install Telethon
pip3 install telethon
# or
pip3 install --user telethon
See Telegram Integration for complete setup.

​
Configuration File (.env)

​
Required Variables

Create a .env file with these credentials:
.env
CLIENT_ID="your-client-id.apps.googleusercontent.com"
CLIENT_SECRET="GOCSPX-your-secret-here"
REFRESH_TOKEN="1//04your-refresh-token-here"
Get these credentials by following the Google Drive API Setup guide.

​
Optional Variables

.env
# Telegram (only if downloading from Telegram)
TELEGRAM_API_ID="12345678"
TELEGRAM_API_HASH="your-api-hash"

# Script options
DEFAULT_FOLDER=""      # Skip folder selection (e.g., "bckups")
DEBUG=0                # Enable debug mode (0 or 1)

​
File Locations

​
Configuration Files

FilePurposeLocation
.envYour credentials~/workspace/source/cloud/gdrive-ingest/.env
.env.exampleTemplate~/workspace/source/cloud/gdrive-ingest/.env.example
Never commit .env to git! It contains sensitive credentials. The .gitignore file should already exclude it.

​
Temporary Files

All temp files are created in /tmp/ with unique process IDs:
  • /tmp/<filename>_$$ - Downloaded files
  • /tmp/extract_$$/ - ZIP extraction
  • /tmp/covers_$$/ - Extracted cover art
See File Organization for details.

​
Session Files

Telegram authentication (persistent): 
~/.config/gdrive-ingest/telegram/downloader.session
Google Drive token cache: 
~/.gdrive_token

​
Testing Your Setup

​
Test 1: Basic Download

./gdrive_ingest.sh https://example.com/test.txt
Expected behavior:
  • Interactive folder selector appears
  • File downloads with progress bar
  • File uploads to selected folder
  • Success message with Google Drive link

​
Test 2: Debug Mode

./gdrive_ingest.sh --debug https://example.com/test.txt
Expected behavior:
  • Shows commands that would run
  • No actual download/upload occurs
  • Useful for troubleshooting
Debug mode is perfect for testing configuration without actually uploading files.

​
Test 3: Music File

./gdrive_ingest.sh https://example.com/song.mp3
Expected behavior:
  • Extracts metadata (Artist, Album, Title)
  • Creates folder structure: Music/Artist/Album (Year)/
  • Extracts and uploads cover art
  • Uploads song to album folder

​
Test 4: Telegram (if configured)

./gdrive_ingest.sh https://t.me/channelname/123
Expected behavior:
  • First run: prompts for phone + verification code
  • Downloads with progress bar
  • Organizes and uploads normally

​
Troubleshooting Setup Issues

Error:
✗ Missing credentials in .env file
Required: CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN
Solution:
  1. Create .env from template: cp .env.example .env
  2. Follow Google Drive API Setup
  3. Add credentials to .env
Error:
ERROR: Refresh failed!
Solution:
  • Check your REFRESH_TOKEN in .env
  • It should start with 1//04... or 1//0g...
  • Regenerate if needed (see Google Drive API Setup)
Solution:
# Ubuntu/Debian
sudo apt install curl

# macOS
brew install curl
Solution:
# Ubuntu/Debian
sudo apt install jq

# macOS
brew install jq
Impact: Music files won’t be organized by artist/album.Solution:
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg
Error:
✗ Telegram API credentials required
Solution:

​
Security Best Practices

Do NOT commit to GitHub:
  • .env file (contains secrets)
  • ~/.config/gdrive-ingest/telegram/ (session files)
  • ~/.gdrive_token (access token cache)
Safe to commit:
  • .env.example (template without secrets)
  • All script files (.sh)
  • Documentation (.md)
Verify .gitignore: 
cat .gitignore | grep .env
Should output: 
.env
.env.local
Additional security tips:
1

Use a dedicated Google account

Consider creating a separate Google account just for this script instead of using your personal account.
2

Restrict file permissions

chmod 600 .env
chmod 600 ~/.gdrive_token
3

Regularly rotate credentials

If you’re paranoid, reset your client secret periodically and regenerate the refresh token.

​
Cleanup and Utilities

​
Cleanup Temp Files

If the script crashes or is interrupted, temp files may remain: 
./cleanup_temp.sh
This removes leftover files from /tmp/gdrive_* and ~/.config/gdrive-ingest/.

​
Telegram Setup Helper

Interactive setup for Telegram credentials: 
./setup_telegram.sh

​
Next Steps

Google Drive API Setup

Get your OAuth credentials

Usage Examples

Learn how to use the script

Interactive Features

Master the interactive UI

Troubleshooting

Fix common issues

Build docs developers (and LLMs) love

Get started for freeTalk to us