Interactive Features

Master the interactive folder browser, keyboard controls, and live progress indicators

Overview

GDrive Ingest features a beautiful interactive CLI with arrow key navigation, live progress bars, and color-coded output. This guide covers all interactive features and keyboard controls.

Interactive Folder Browser

Launching Interactive Mode

Run the script without the --folder flag:

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

You’ll see the folder browser:

╭───────────────────────────────────────────────────────╮
│  📁 Select Destination Folder                         │
├───────────────────────────────────────────────────────┤
│  ↑/↓: Navigate  →: Open  ←: Back  Enter: Select      │
╰───────────────────────────────────────────────────────╯

  ▶ ● Create new folder
  ○ Music
  ○ Images
  ○ Videos
  ○ Documents

Keyboard Controls

Navigation Keys

Key	Action	Description
↑	Move Up	Navigate to previous folder
↓	Move Down	Navigate to next folder
→	Open Folder	Enter the selected folder
←	Go Back	Return to parent folder
Enter	Select	Choose the highlighted folder
q	Quit	Exit the script

Visual Indicators

Symbol	Meaning
▶	Currently selected (highlighted)
○	Not selected (empty circle)
●	Action items (create, select)
◂	Back option

Navigation Examples

1. Browse root folders

   Use ↑/↓ to move through top-level folders:

   ▶ ● Create new folder
     ○ Music
     ○ Videos
   
2. Enter a folder

   Highlight “Music” and press →:

   ▶ ◂ Back
     ● Select this folder
     ○ Artist 1
     ○ Artist 2
   
3. Go deeper

   Select an artist and press → again:

   ▶ ◂ Back
     ● Select this folder
     ○ Album 1 (2024)
     ○ Album 2 (2023)
   
4. Go back

   Press ← to return to the parent folder

5. Select destination

   Highlight your choice and press Enter

Special Options

Create New Folder

At the root level:

1. Select 'Create new folder'

   ▶ ● Create new folder  <-- Select this
     ○ Music
     ○ Videos
   

   Press Enter

2. Enter folder name

   Enter new folder name: My Archive
   
3. Folder created

   ✓ Created folder
   ✓ Selected: My Archive (ID: ...)
   

Select Current Folder

When inside a folder:

  ○ ◂ Back
  ▶ ● Select this folder  <-- Select to upload here
    ○ Subfolder 1
    ○ Subfolder 2

Press Enter to upload to the current folder (not a subfolder).

Type Folder Name or ID

At the root level:

▶ ✎ Type folder name/ID  <-- Select this
  ○ Music
  ○ Videos

1. Select 'Type folder name/ID'

   Press Enter

2. Enter name or ID

   By name:

   Enter folder name or ID: Music
   Searching for folder...
   ✓ Found folder
   

   By ID:

   Enter folder name or ID: 1hU4H0PO_ifwGP47UZHwbc2w89Y7V_YPn
   ✓ Selected: (ID: 1hU4H0PO_...)
   
3. Create if not found

   If folder doesn’t exist:

   Folder not found. Create it? (y/n): y
   Creating folder...
   ✓ Created folder
   

Live Progress Indicators

Download Progress Bar

Real-time download progress with percentage:

⬇  [████████████████████░░░░░░░░░░] 65%

Features:

• Live percentage updates
• Visual bar graph
• Updates every 100ms
• ASCII-safe (works in any terminal)

Complete download:

⬇  [████████████████████████████████████████] 100%
✓ Download complete

Upload Progress with Spinner

Uploads show a spinner with file size:

   ⬆  Uploading 8.52MB... ⠋

Spinner characters:

⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏

(Braille pattern dots - smooth animation)

Complete upload:

   ✓ Uploaded 8.52MB          

Cover Art Upload

   🖼  Cover art... ⠇
   ✓ Cover art uploaded

Color-Coded Output

Color Meanings

Status Colors

Color	Used For	Example
🔴 Red	Errors, failures	✗ Upload failed
🟢 Green	Success, checkmarks	✓ Download complete
🟡 Yellow	Warnings, downloads	⬇ Downloading...
🔵 Blue	Info, metadata	🔐 MD5: 6d2300f6...
🟣 Magenta	Headers, music info	💿 Artist - Album
🔷 Cyan	Progress, actions	Organizing files...

Text Styles

Style	Used For	Example
Bold	Important text	Music/Artist/Album
Dim	Secondary info	(ID: 1hU4H0PO_…)

Example Output

✓ Using cached access token  # Green
📦 Processing 1 URL(s)        # Magenta

[1/1] Processing: https://...  # Cyan
─────────────────────────
⬇  Downloading song.mp3...    # Yellow
✓ Download complete           # Green
🔐 MD5: 6d2300f6a025e07ad...  # Blue
💿 Artist - Album - Title    # Magenta
   ⬆  Uploading 8.52MB...      # Cyan
   ✓ Uploaded 8.52MB          # Green

Usage Modes

Interactive Mode (No —folder flag)

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

Features:

• Arrow key navigation
• Browse nested folders
• Create folders on the fly
• Visual folder tree

Best for:

• Exploring your Drive structure
• One-off uploads
• Organizing files manually

Command-Line Mode (With —folder flag)

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

Features:

• Skips interactive browser
• Direct upload to specified folder
• Creates folder if it doesn’t exist
• Faster for automation

Best for:

• Automation scripts
• Batch processing
• Known destination folders

Debug Mode

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

Features:

• Shows commands without executing
• Displays API queries
• Shows duplicate checks
• No actual upload occurs

Best for:

• Testing configuration
• Troubleshooting issues
• Understanding script behavior

Example Interactive Session

1. Launch script

   ./gdrive_ingest.sh https://example.com/song.mp3
   
2. Token refresh

   ✓ Using cached access token (valid until ...)
   📦 Processing 1 URL(s)
   Fetching your GDrive folders...
   
3. Folder selection

   ╭───────────────────────────────────────╮
   │  📁 Select Destination Folder     │
   ├───────────────────────────────────────┤
   │  ↑/↓: Navigate  Enter: Select  │
   ╰───────────────────────────────────────╯
   
     ○ ● Create new folder
     ▶ Music
     ○ Images
   

   Press Enter to select Music

4. Confirmation

   ✓ Selected: Music (ID: 1hU4H0PO_ifwGP47UZHwbc2w89Y7V_YPn)
   
5. Download

   [1/1] Processing: https://example.com/song.mp3
   ────────────────────────────────────────
   ⬇  [████████████████████████████████████████] 100%
   ✓ Download complete
   🔐 MD5: 6d2300f6a025e07ad87991b31023da6a
   
6. Organization

   📄 Single file
   Organizing and uploading files...
   💿 Don Toliver - Tiramisu (2025) - Tiramisu
   
7. Upload

      ⬆  Uploading 8.52MB... ⠋
      ✓ Uploaded 8.52MB
      🖼  Cover art... ⠇
      ✓ Cover art uploaded
   
8. Complete

   ────────────────────────────────────────
   ✓ Done! Files uploaded to GDrive: Music
   🔗 Check: https://drive.google.com/drive/folders/...
   ────────────────────────────────────────
   

Technical Details

Terminal Controls

Feature	Implementation	Purpose
Cursor hiding	tput civis	Clean UI without flicker
Cursor showing	tput cnorm	Restored on exit
ANSI colors	Escape codes	Color-coded output
Raw input	read -rsn1	Single keypress detection
Cleanup trap	trap cleanup EXIT	Ensures cursor restored

Progress Implementations

Download progress:

• Parses curl output in real-time
• Extracts percentage from progress bar
• Updates display every 100ms

Upload progress:

• Background curl process
• Foreground spinner animation
• PID monitoring with kill -0

Navigation Logic

Recursive folder browsing:

1. Fetch all folders (single API call)
2. Filter by parent ID
3. Display current level
4. Track navigation history
5. Return to parent on ←

Root detection:

• Special handling for root-level folders
• Different options at root vs nested levels

Pro Tips

Quick Navigation

Use → to dive deep, ← to go back quickly

Automation

Use --folder flag for scripts and automation

Exploration

Omit --folder to browse interactively

Create on Fly

Select “Create new folder” to organize as you go

Visual Feedback

Watch spinners to confirm uploads are working

Debug First

Test with --debug before actual uploads

Next Steps

Usage Examples

See real-world usage patterns

File Organization

Understand how files are organized

Troubleshooting

Fix common issues

Setup Guide

Configure the script