Quick start - TheTeleporter Scripts

Before you begin

Make sure you’ve completed the installation guide and have:

Cloned the repository to ~/scripts
Installed core dependencies (bash, curl, jq, ffmpeg)
Made scripts executable with chmod +x

This guide focuses on GDrive Ingest, the flagship script for uploading files to Google Drive.

Set up Google Drive API

Before using GDrive Ingest, you need to configure Google Drive API credentials.

Create environment file

Navigate to the GDrive Ingest directory and create your configuration:

cd ~/scripts/cloud/gdrive-ingest
cp .env.example .env
nano .env

Get Google Drive credentials

You’ll need three pieces of information:

CLIENT_ID - OAuth 2.0 client ID from Google Cloud Console
CLIENT_SECRET - OAuth 2.0 client secret
REFRESH_TOKEN - Long-lived token for accessing your Drive

See the detailed Google Drive setup guide for instructions on obtaining these credentials.

Add credentials to .env

Edit .env and add your credentials:

.env

CLIENT_ID="your-client-id.apps.googleusercontent.com"
CLIENT_SECRET="GOCSPX-your-secret-key"
REFRESH_TOKEN="1//04your-long-refresh-token"

Your first upload

Let’s upload a file to Google Drive using the interactive interface.

Basic usage

Run the script with a URL to a file you want to download and upload:

./gdrive_ingest.sh https://example.com/song.mp3

Interactive folder browser

The script will launch an interactive folder browser:

┌─ Select Destination Folder ─────────────────────────┐
│                                                      │
│  > Music                                             │
│    Images                                            │
│    Videos                                            │
│    Documents                                         │
│    Backups                                           │
│                                                      │
│  [↑↓] Navigate  [→] Enter  [←] Back  [q] Quit       │
└──────────────────────────────────────────────────────┘

Navigation controls:

↑ / ↓ - Move up and down through folders
→ - Enter the selected folder
← - Go back to parent folder
Enter - Select the current folder as destination
q - Quit the browser

The folder browser shows your actual Google Drive folder structure in real-time.

Watch the progress

Once you select a destination, the script will:

Download the file with a live progress bar
Extract metadata (for audio files)
Organize into the appropriate folder structure
Upload to Google Drive with progress tracking
Clean up temporary files

Example output:

✓ Downloading: song.mp3
[████████████████████████████] 100% - 3.2 MB/s

ℹ Processing audio file...
ℹ Artist: The Beatles
ℹ Album: Abbey Road (1969)
✓ Extracted cover art

✓ Uploading to: Music/The Beatles/Abbey Road (1969)/
[████████████████████████████] 100% - Complete

✓ Upload successful!
✓ Cleaned up temp files

Skip the interactive browser

If you already know which folder you want to upload to, skip the interactive browser:

./gdrive_ingest.sh --folder "Music" https://example.com/song.mp3

The script will go directly to that folder without prompting.

Upload multiple files

You can upload multiple files in one command:

Multiple URLs as arguments

./gdrive_ingest.sh \
  https://example.com/song1.mp3 \
  https://example.com/song2.mp3 \
  https://example.com/song3.mp3

Comma-separated URLs

./gdrive_ingest.sh "url1.mp3,url2.mp3,url3.mp3"

From a JSON file

Create a JSON file with your URLs:

urls.json

[
  "https://example.com/song1.mp3",
  "https://example.com/song2.mp3",
  "https://example.com/album.zip"
]

Then upload from the file:

./gdrive_ingest.sh --json urls.json

Smart music organization

For audio files, GDrive Ingest automatically:

Extracts artist, album, and year from metadata
Organizes into Artist/Album (Year)/ folder structure
Extracts and uploads cover art as cover.jpg
Cleans metadata to remove website tags
Detects and skips duplicate files

Example organization:

Music/
└── Pink Floyd/
    └── The Dark Side of the Moon (1973)/
        ├── 01 - Speak to Me.mp3
        ├── 02 - Breathe.mp3
        ├── 03 - On the Run.mp3
        └── cover.jpg

Non-music files are organized by type: Images, Videos, Documents, or Others.

Download from Telegram (optional)

If you’ve set up Telegram support, you can download files from Telegram channels:

./gdrive_ingest.sh https://t.me/channelname/123

First-time setup: On your first Telegram download, you’ll be prompted to:

Enter your phone number (with country code)
Enter the verification code sent to Telegram
(Optional) Enter 2FA password if enabled

Subsequent downloads will use the saved session.

Debug mode

Test the script without actually downloading or uploading:

./gdrive_ingest.sh --debug https://example.com/file.mp3

Debug mode shows what commands would be executed without performing actual operations.

Common use cases

Upload a single song

./gdrive_ingest.sh https://example.com/awesome-song.mp3

Use the interactive browser to navigate to your Music folder.

Backup multiple files directly

./gdrive_ingest.sh --folder "Backups" \
  https://example.com/backup1.zip \
  https://example.com/backup2.zip

Organize an album from a ZIP file

./gdrive_ingest.sh --folder "Music" https://example.com/album.zip

The script will:

Download and extract the ZIP
Detect audio files inside
Organize each track by artist/album
Upload with cover art

Download Telegram music channel

./gdrive_ingest.sh --folder "Music" \
  https://t.me/musicchannel/501 \
  https://t.me/musicchannel/502 \
  https://t.me/musicchannel/503

Clean up temporary files

GDrive Ingest creates temporary files in /tmp/gdrive_* during operation. These are automatically cleaned up after each upload. If you need to manually clean up:

./cleanup_temp.sh

This removes:

All /tmp/gdrive_* directories
Session files in ~/.config/gdrive-ingest/
Leftover lock files

Get help

View all available options and examples:

./gdrive_ingest.sh --help

Example output:

gdrive_ingest.sh - Ultimate Google Drive cloud ingestor

USAGE:
  ./gdrive_ingest.sh [OPTIONS] [URL...]

OPTIONS:
  -h, --help              Show this help message
  -d, --debug             Debug mode (dry-run, show commands)
  -f, --folder <name>     Destination folder (skips interactive mode)
  -j, --json <file>       Load URLs from JSON file

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

Other system tools

Try other scripts in the collection:

Power Guard

Monitor and manage CPU-intensive processes:

cd ~/scripts/system
./power_guard.sh

This script identifies processes using more than 30% CPU and terminates them (except whitelisted system processes).

Create your own script

Use the template to build custom automation:

cp ~/scripts/templates/script-template.sh ~/scripts/my-script.sh
chmod +x ~/scripts/my-script.sh
nano ~/scripts/my-script.sh

The template includes:

Argument parsing
Color-coded output functions
Error handling
Help documentation
Debug mode support

Troubleshooting

”Missing credentials in .env file”

You haven’t set up your Google Drive API credentials yet. See step 1 of this guide.

”TELEGRAM_API_ID required”

You’re trying to download from Telegram without setting up credentials. Either:

Add Telegram credentials to .env (see installation guide)
Don’t use Telegram URLs

”database is locked” (Telegram)

A previous Telegram session didn’t close properly. Remove the lock file:

rm ~/.config/gdrive-ingest/telegram/*.session-journal

Upload fails silently

Check if the file was downloaded:

ls -la /tmp/gdrive_*

Run with debug mode to see detailed output:

./gdrive_ingest.sh --debug your-url

“ffprobe: command not found”

You haven’t installed ffmpeg. See the installation guide for instructions.

Next steps

Now that you’re familiar with the basics, explore more features:

Google Drive setup

Detailed guide for obtaining Google Drive API credentials

Telegram setup

Configure Telegram support for downloading from channels

Advanced features

Learn about duplicate detection, metadata cleaning, and more

System tools

Explore other automation scripts in the collection

Get Started

Scripts

GDrive Ingest

Development

​Before you begin

​Set up Google Drive API

​Your first upload

​Basic usage

​Interactive folder browser

​Watch the progress

​Skip the interactive browser

​Upload multiple files

​Multiple URLs as arguments

​Comma-separated URLs

​From a JSON file

​Smart music organization

​Download from Telegram (optional)

​Debug mode

​Common use cases

​Upload a single song

​Backup multiple files directly

​Organize an album from a ZIP file

​Download Telegram music channel

​Clean up temporary files

​Get help

​Other system tools

​Power Guard

​Create your own script

​Troubleshooting

​”Missing credentials in .env file”

​”TELEGRAM_API_ID required”

​”database is locked” (Telegram)

​Upload fails silently

​“ffprobe: command not found”

​Next steps

Google Drive setup

Telegram setup

Advanced features

System tools

Build docs developers (and LLMs) love

Before you begin

Set up Google Drive API

Your first upload

Basic usage

Interactive folder browser

Watch the progress

Skip the interactive browser

Upload multiple files

Multiple URLs as arguments

Comma-separated URLs

From a JSON file

Smart music organization

Download from Telegram (optional)

Debug mode

Common use cases

Upload a single song

Backup multiple files directly

Organize an album from a ZIP file

Download Telegram music channel

Clean up temporary files

Get help

Other system tools

Power Guard

Create your own script

Troubleshooting

”Missing credentials in .env file”

”TELEGRAM_API_ID required”

”database is locked” (Telegram)

Upload fails silently

“ffprobe: command not found”

Next steps