googleClient

Purpose

This project was created to solve a real-world need for a growing business.
One of our clients — a cloud-native compounding pharmacy — started small with just a few users on Google Workspace. Over time, they grew to more than 75 users, but their SOPs and critical documents ended up scattered across personal Google Drives.

The request was to centralize documents in order to:

• Improve corporate control and governance
• Enable DLP (Data Prevention) policies
• Simplify off-boarding processes
• Improve monitoring of file usage and sharing

To prepare for this migration, we needed a way to inspect ("poke around") all user drives without modifying anything:

• No content changes
• No access time updates
• No permissions modified

googleClient was built as a command-line tool using Google Workspace Domain-Wide Delegation. It allows administrators to explore user drives safely and efficiently, providing insight into the file landscape before making structural changes.

Features

• Virtual Home Root: Toggle between a user's personal 'My Drive' and a discovery view of 'Shared with me' folders.
• Identity Awareness: Dynamic 'Owner' identification column in file listings to identify data sprawl.
• Impersonation: Impersonate any user (via DWD).
• FTP-like Navigation: ls, ls #, cd, pwd.
• Advanced Fetching: get with ranges and globs (e.g. get 5-9,11 or get *.pdf).
• Bulk Download: mget * to download all files in the current list.
• Auditing Tools: search, recent, info, perms, rawname.
• User History: History (last 50 commands) tracked per impersonated user.
• Hardened Security: Secret loading from SA_JSON_B64 / SA_JSON env or --key (0600).
• Colorized UI: Output colorized based on filetype and ownership (shared items highlighted in pink).
• TUI Interactive Mode: Full terminal UI (--tui) with clickable column-header sorting (Name, Type, Owner, Modified), multi-select, action menu, and an integrated command bar.

Quick start

python3 -m venv .venv && source .venv/bin/activate
pip install .
export SA_JSON_B64="$(base64 -w0 path/to/service_account.json)"
gC --user someone@yourdomain.com

---

Setup

1. Create a Service Account

1. Go to Google Cloud Console.
2. Create a new Project (or use an existing one).
3. Navigate to IAM & Admin → Service Accounts.
4. Click Create Service Account and give it a name.
5. Assign the role Google Drive Viewer (or required scope for your script).
6. Click Done.

2. Create and Download the Key

1. In the Service Accounts list, click your new account.
2. Go to the Keys tab.
3. Click Add Key → Create New Key.
4. Choose JSON and click Create.
5. Save this file as service_account.json in your project directory.

Security note:
If stored on disk, restrict permissions:

chmod 600 service_account.json

Alternatively, store it securely in an environment variable:

export SA_JSON_B64="$(base64 -w0 service_account.json)"

3. Enable APIs

1. In Google Cloud Console, go to APIs & Services → Library.
2. Enable the Google Drive API.

---

Troubleshooting

• Ensure your service_account.json is valid and has the correct scope.
• Double-check API is enabled for the project.
• Confirm environment variables are correctly set.

---

Usage Examples

gC --user alice@yourdomain.com
ls          # Shows 'My Drive' and 'Shared with me'
cd 2        # Enter 'Shared with me'
ls          # List shared folders and their owners
perms 1     # Audit permissions of a specific folder

Colorized Output

googleClient colorizes CLI output based on file type and ownership for easier scanning. Items shared with the user (not owned by them) are highlighted in a distinct pink.

Config File Location

Default path: ~/.config/gC/colors.toml Override via GC_CONFIG environment variable.

Supported Color Names

Any standard ANSI colors or 256-color palette indices (e.g., pink uses index 224).

Commands

Navigation

• cd <#|..|/>
  Change directory by index, go up to the Virtual Home, or return to the Home root (/).

• ls [#]
  List current directory. At the Home root, displays 'My Drive' and 'Shared with me'. Optionally provide an index to "peek" inside a folder without changing directories.

• pwd
  Show the current path.

File Operations

• get <#|#-#|#,#,...|glob>
  Download files by index, range, or glob.

• mget *
  Download all files in the current list.

Metadata & Permissions

• info <#>
  Show detailed JSON metadata for a file/folder.

• perms <#>
  Show the email addresses and roles for all users with access to the item.

• rawname <#>
  Show the raw underlying name (repr) for the file/folder.

Search & Listing

• search "<namepart>"
  Search current folder for items matching a substring.

• recent [hours]
  List files modified in the last N hours (default = 48).

• size [-L#] [-B|K|M|G] [--follow-shortcuts] [#]
  Recursively sum file sizes.

• tree [-L#] [-d] [--follow-shortcuts] [#]
  Print a visual directory tree.

---

TUI — Interactive Mode

Launch the TUI instead of the REPL prompt:

gC --user someone@yourdomain.com --tui

Layout

Area	Description
Header bar	Current impersonated user and folder breadcrumb
File table	#, Type, Owner, Modified, Name columns; rows colourised by ownership
Detail pane	Toggled with d — shows metadata for the highlighted row
Command bar	Bottom input; focus with Ctrl+L; accepts all REPL commands
Status bar	Item count and current path

Navigation

Key	Action
↑ / ↓	Move cursor
Enter	Open folder / enter directory
← / Left	Go up one level
r	Refresh current folder
d	Toggle detail pane
q	Quit

Multi-select

Key	Action
t	Tag and advance — toggle current row then move cursor down
Ctrl+Space	Toggle current row (cursor stays)
Shift+↓ / Shift+↑	Extend range selection
Ctrl+A	Select all rows
Esc	Clear selection / return focus to table

Tip: Use t to rapidly pick scattered files: press it on each file you want without touching the arrow keys. Mix arrow keys to skip rows you don't want.

Sorting

Click any column header to sort the file list:

Click	State	Header shows
1st	A → Z	Name ▲
2nd	Z → A	Name ▼
3rd	Original API order	Name

• Clicking a different column resets to A → Z for that column.
• Sort persists as you navigate into subfolders.
• The # column header is not sortable.

Action menu (Space)

Press Space to open a context menu for the highlighted item (or, if rows are selected, for the whole selection):

Context	Options
File selected	Download · Info / metadata · Permissions
Folder selected	Open · Bulk Download (mget -r) · Tree · Permissions
N items tagged	Download selected (N items)

Downloads go to the current working directory by default. The first time you download something the TUI prompts you to confirm or change the download folder for the session.

Command bar

Press Ctrl+L to focus the command bar, then type any REPL command (ls, cd, get, search, info, perms, tree, size, …) and press Enter. Output is shown in the status bar or detail pane. Press Esc to return focus to the table.

Colour coding

Colours follow the same rules as the REPL:

• Items owned by the impersonated user — standard colours by file type
• Items shared with the user (not owned) — highlighted in pink

---

Future Features

1. search command enhancements
   • Add recursive search (-r) and depth limits (-L <n>).
2. get command enhancements
   • Add recursive folder downloading.
3. info command enhancement
   • Improve shortcutDetails display to show target metadata at a glance.