tgcp - Terminal UI for GCP

tgcp provides a terminal UI to interact with your Google Cloud Platform resources. The aim of this project is to make it easier to navigate, observe, and manage your GCP infrastructure in the wild. tgcp continually watches GCP for changes and offers subsequent commands to interact with your observed resources.

Screenshots

Features

• Multi-Project Support - Easily switch between GCP projects
• Multi-Zone Support - Navigate across different zones and regions
• 60+ Resource Types - Browse and manage resources across 30+ GCP services
• Real-time Updates - Auto-refresh resources every 5 seconds
• Keyboard-Driven - Vim-like navigation and commands
• Detailed Views - JSON view of resource details with syntax highlighting
• Filtering - Filter resources by name or attributes
• Autocomplete - Smart resource type autocomplete with fuzzy matching
• No gcloud dependency - Native authentication, works standalone
• Persistent Config - Remembers your last project and zone

Installation

Homebrew (macOS/Linux)

brew install huseyinbabal/tap/tgcp

Scoop (Windows)

scoop bucket add huseyinbabal https://github.com/huseyinbabal/scoop-bucket
scoop install tgcp

Download Pre-built Binaries

Download the latest release from the Releases page.

Quick Install (macOS/Linux)

# macOS Apple Silicon
curl -sL https://github.com/huseyinbabal/tgcp/releases/latest/download/tgcp-aarch64-apple-darwin.tar.gz | tar xz
sudo mv tgcp /usr/local/bin/

# macOS Intel
curl -sL https://github.com/huseyinbabal/tgcp/releases/latest/download/tgcp-x86_64-apple-darwin.tar.gz | tar xz
sudo mv tgcp /usr/local/bin/

# Linux x86_64 (musl - works on Alpine, Void, etc.)
curl -sL https://github.com/huseyinbabal/tgcp/releases/latest/download/tgcp-x86_64-unknown-linux-musl.tar.gz | tar xz
sudo mv tgcp /usr/local/bin/

# Linux ARM64 (musl - works on Alpine, Void, etc.)
curl -sL https://github.com/huseyinbabal/tgcp/releases/latest/download/tgcp-aarch64-unknown-linux-musl.tar.gz | tar xz
sudo mv tgcp /usr/local/bin/

Windows

1. Download tgcp-x86_64-pc-windows-msvc.zip from the Releases page
2. Extract the zip file
3. Add the extracted folder to your PATH, or move tgcp.exe to a directory in your PATH

Using Cargo

cargo install tgcp

Using Docker

# Run interactively
docker run --rm -it ghcr.io/huseyinbabal/tgcp

# Launch with GCP credentials (mount gcloud config)
docker run --rm -it \
  -v ~/.config/gcloud:/root/.config/gcloud:ro \
  ghcr.io/huseyinbabal/tgcp

# Launch in a specific zone
docker run --rm -it \
  -v ~/.config/gcloud:/root/.config/gcloud:ro \
  ghcr.io/huseyinbabal/tgcp --zone us-central1-a

# Using service account JSON
docker run --rm -it \
  -v /path/to/service-account.json:/credentials.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/credentials.json \
  ghcr.io/huseyinbabal/tgcp

# Using environment variables
docker run --rm -it \
  -e GCP_ACCESS_TOKEN=$GCP_ACCESS_TOKEN \
  ghcr.io/huseyinbabal/tgcp

# Build locally
docker build -t tgcp .
docker run --rm -it -v ~/.config/gcloud:/root/.config/gcloud:ro tgcp

Note: Use -it flags for interactive terminal support (required for TUI). Mount your ~/.config/gcloud directory as read-only to use your existing GCP credentials.

From Source

tgcp is built with Rust. Make sure you have Rust 1.70+ installed, along with a C compiler and linker.

# Clone the repository
git clone https://github.com/huseyinbabal/tgcp.git
cd tgcp

# Build and run
cargo build --release
./target/release/tgcp

Prerequisites

• GCP Credentials - See Authentication section below
• IAM Permissions - Your GCP user/service account needs appropriate read permissions for the services you want to browse. At minimum, you'll need Viewer role or specific *.get and *.list permissions.

Authentication

tgcp uses a credential chain, trying each source in order:

Using Application Default Credentials (Recommended for Development)

# Login and create ADC file
gcloud auth application-default login

# Then simply run tgcp
tgcp

Using Service Account

# Set path to service account JSON
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
tgcp

# Or inline JSON
export GOOGLE_CREDENTIALS='{"type":"service_account","project_id":"..."}'
tgcp

Running on GCP Infrastructure

When running on Compute Engine, Cloud Run, or GKE, tgcp automatically uses the metadata server for authentication. No configuration needed.

Quick Start

# Launch tgcp (uses default project from credentials)
tgcp

# Launch in a specific zone
tgcp --zone us-central1-a

# Launch in read-only mode (blocks all write operations)
tgcp --readonly

# Enable debug logging
tgcp --log-level debug

Key Bindings

Supported GCP Services (60+ Resources)

tgcp supports 30+ GCP services with 60+ resource types:

Compute & Containers

Networking

Storage & Databases

Data & Analytics

Security & Identity

DevOps & CI/CD

Operations

Missing a service? Start a discussion to propose adding it!

Configuration

Config File

tgcp stores configuration in ~/.config/tgcp/config.yaml:

project: my-gcp-project
zone: us-central1-a
last_resource: vm-instances

Environment Variables

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Important: Before adding a new GCP service, please start a discussion first.

Acknowledgments

• Inspired by k9s - the awesome Kubernetes CLI
• Sister project to taws - Terminal UI for AWS
• Built with Ratatui - Rust TUI library

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for the GCP community