TGCP (Terminal GCP Explorer)

Website | GitHub | Releases

TGCP is a terminal-based user interface for observing and managing Google Cloud Platform resources, inspired by tools like K9s and TAWS. It provides a fast, keyboard-driven experience for DevOps engineers and Cloud Administrators.

• 💡 Observability First: Designed for reading statuses, logs, and configurations quickly.
• 🚀 Fast Navigation: Global vim-style keybindings (j/k, Shift+H/L).
• 🔐 Secure Authentication: Uses Application Default Credentials (ADC) - no new keys to manage.
• ⚡ Smart Caching: Instant tab switching with background data refreshes.
• 🖱️ Mouse Support: Click to select items; hold Shift to select text.
• 🛠️ Service Support:
  • Compute: GCE Instances (Manage power state, SSH), GKE Clusters (Launch k9s), Cloud Run & Cloud Functions.
  • Storage: GCS Buckets, Persistent Disks.
  • Databases: Cloud SQL, Spanner, Bigtable, Memorystore (Redis), Firestore.
  • Data & Analytics: BigQuery, Dataflow, Dataproc, Pub/Sub.
  • Security & Networking: IAM, Secret Manager, VPCs, Subnets, Firewalls.
  • Observability: Cloud Logging.
  • DevOps: Cloud Build, Artifact Registry.
• 🛡️ Safety: Read-only by default for sensitive configs; confirmation dialogs for actions.
• 📚 Documentation:
  • Feature Deep Dive
  • Developer Guide
  • UI Patterns

Installation

Prerequisites

• Google Cloud SDK (gcloud) installed and configured

macOS (Homebrew)

brew tap yogirk/tap
brew install tgcp

To upgrade to the latest version:

brew upgrade tgcp

Linux

Pick the archive for your architecture from the Releases page, or use this version-agnostic snippet:

ARCH=amd64   # or arm64
VERSION=$(curl -s https://api.github.com/repos/yogirk/tgcp/releases/latest | grep tag_name | cut -d'"' -f4 | tr -d 'v')
curl -L "https://github.com/yogirk/tgcp/releases/latest/download/tgcp_${VERSION}_linux_${ARCH}.tar.gz" | tar -xz
sudo mv tgcp /usr/local/bin/

Go Install

Requires Go 1.21 or higher.

go install github.com/yogirk/tgcp/cmd/tgcp@latest

Build from Source

Requires Go 1.21 or higher.

git clone https://github.com/yogirk/tgcp.git
cd tgcp
go build -o tgcp ./cmd/tgcp
sudo mv tgcp /usr/local/bin/

Setup & Authentication

TGCP uses Application Default Credentials (ADC) to authenticate with Google Cloud.

1. Login with gcloud:

   gcloud auth application-default login

2. Verify Project: Ensure your default project is set in gcloud:

   gcloud config set project [YOUR_PROJECT_ID]

Usage

Run the application:

tgcp

Configuration

TGCP supports a configuration file at ~/.tgcprc (YAML format).

The left-side sidebar is hidden by default (toggle it anytime with Ctrl+b); set ui.sidebar_visible: true to have it shown on startup instead.

Example ~/.tgcprc:

project: "my-default-project"
ui:
  sidebar_visible: true

# Optional: a fixed list of projects to jump between with Ctrl+g (the quick
# project switcher), instead of paging through every project your account
# can see.
projects:
  - id: "my-default-project"
    name: "Prod"
  - id: "my-dev-project"
    name: "Dev"

# Optional: retention for the "Job History" view (every create/update/
# delete/etc. you perform, persisted to ~/.tgcp/jobs.json). Both limits
# always apply together; set either to 0 or less to make it unbounded.
jobs:
  max_count: 500     # keep at most this many jobs (default 500)
  max_age_days: 30   # drop jobs older than this many days (default 30)

CLI Options

Flag	Description
--project <ID>	Override the default project ID for this session.
--debug	Enable verbose logging to ~/.tgcp/debug.log.
--version	Display version information.
--help	Show help message.

Keybindings

Global

Key	Action
q	Quit application or Go Back
?	Toggle Help overlay
:	Open Command Palette
/	Filter current list
Ctrl+c	Force Quit
Ctrl+b	Toggle Sidebar visibility
Ctrl+g	Quick-switch to a project from ~/.tgcprc's projects: list

Navigation

Key	Action
↑ / k / Ctrl+p	Move selection up
↓ / j / Ctrl+n	Move selection down
Enter	Select item / View Details
Tab / Shift+Tab	Next / Previous tab (where a service has tabs)
Click	Select item (mouse/trackpad)
Shift+Drag	Select text for copy

Service Actions

Key	Action	Context
r	Refresh data (bypassing cache)	Global
s	Start resource	GCE, Cloud SQL
x	Stop resource	GCE, Cloud SQL
h	SSH into instance	GCE
K	Launch k9s	GKE
[ / ] / Tab / Shift+Tab	Switch Tabs	Cloud Run, Load Balancing, VPC Network, Cloud Monitoring
Enter	Drill Down / Open	GCS Object Browser, BigQuery
Esc	Go Back / Up Level	GCS Object Browser, BigQuery

Troubleshooting

"Authentication Error" Screen

Cause: The application cannot find valid credentials. Fix: Run gcloud auth application-default login. If that fails, ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is pointing to a valid key file.

"No Project ID"

Cause: The ADC credentials didn't contain a quota project, and no project was specified in flags. Fix: Run gcloud config set project <PROJECT_ID> or run tgcp with tgcp --project <PROJECT_ID>.

API Errors (403, etc.)

Cause: Your credentials might not have permissions for the specific service (e.g., Compute Viewer). Fix: Ensure your user account or service account has the necessary IAM roles.

Development

• Run in debug mode: go run ./cmd/tgcp --debug
• View logs: tail -f ~/.tgcp/debug.log
• Run tests: go test ./...

License

MIT