tgcp

Terminal UI for Google Cloud Platform

A fast, keyboard-driven terminal interface for navigating and managing Google Cloud Platform resources. Inspired by vim, built with Rust.

┌─────────────────────────────────────────────────────────────────────────────┐
│  tgcp                          my-project  │  us-central1-a  │  instances  │
├─────────────────────────────────────────────────────────────────────────────┤
│  NAME                 STATUS     MACHINE TYPE     ZONE            IP        │
│  ─────────────────────────────────────────────────────────────────────────  │
│▸ web-server-01        RUNNING    e2-medium        us-central1-a   10.0.0.2  │
│  web-server-02        RUNNING    e2-medium        us-central1-a   10.0.0.3  │
│  database-primary     RUNNING    n2-standard-4    us-central1-a   10.0.0.4  │
│  batch-worker-01      STOPPED    e2-small         us-central1-a   -         │
│  dev-instance         RUNNING    e2-micro         us-central1-a   10.0.0.6  │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  j/k:navigate  d:describe  s:start  S:stop  p:project  z:zone  ?:help  q:quit│
└─────────────────────────────────────────────────────────────────────────────┘

Features

• Vim-style navigation - j/k, gg, G, / search, : commands
• Multi-resource support - VMs, disks, networks, buckets, GKE clusters
• Hierarchical browsing - Navigate from VMs to disks, buckets to objects
• Resource actions - Start, stop, reset, delete with confirmation dialogs
• SSH integration - Connect to VMs with x, IAP tunneling with X
• Cloud Monitoring metrics - Live CPU, RAM, Disk I/O, Network stats for VMs with trend indicators
• Column configuration - Show/hide columns per resource type with o key
• Theme system - 7 built-in themes with per-project support
• Real-time filtering - Instant search across resource lists
• Project/zone switching - Quick context changes without leaving the app
• Command aliases - Create shortcuts for frequently used resources
• Read-only mode - Safe exploration with --readonly flag
• All-zones view - See resources across all zones at once
• JSON detail view - Full resource inspection with d key
• Async & fast - Non-blocking API calls with pagination support

Installation

From pre-built binaries (recommended)

Download the latest release for your platform from the releases page:

# Linux x86_64 (GNU)
curl -L https://github.com/MrMichou/tgcp/releases/latest/download/tgcp-linux-x86_64.tar.gz | tar xz
sudo mv tgcp /usr/local/bin/

# Linux x86_64 (musl - static binary)
curl -L https://github.com/MrMichou/tgcp/releases/latest/download/tgcp-linux-x86_64-musl.tar.gz | tar xz
sudo mv tgcp /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/MrMichou/tgcp/releases/latest/download/tgcp-darwin-aarch64.tar.gz | tar xz
sudo mv tgcp /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/MrMichou/tgcp/releases/latest/download/tgcp-darwin-x86_64.tar.gz | tar xz
sudo mv tgcp /usr/local/bin/

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/MrMichou/tgcp/releases/latest/download/tgcp-windows-x86_64.zip" -OutFile "tgcp.zip"
Expand-Archive -Path "tgcp.zip" -DestinationPath "."

From source

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

# Build release binary
cargo build --release

# Install to ~/.cargo/bin
cargo install --path .

Prerequisites

• Rust stable (latest recommended)
• Google Cloud SDK (gcloud) configured with credentials

Quick Start

1. Authenticate with GCP

   gcloud auth application-default login

2. Set default project and zone (optional)

   gcloud config set project my-project
   gcloud config set compute/zone us-central1-a

3. Launch tgcp

   tgcp

   Or with explicit project/zone:

   tgcp --project my-project --zone us-central1-a

Keyboard Shortcuts

Navigation

Key	Action
j / ↓	Move down
k / ↑	Move up
gg	Go to first item
G	Go to last item
[ / ]	Previous / next page
b / Backspace	Go back

Actions

Key	Action
Enter / d	View resource details (JSON)
s	Start instance
S	Stop instance
Ctrl+r	Reset instance
x	SSH to instance
X	SSH via IAP tunnel
C	Open in GCP Console
Ctrl+d	Delete resource (with confirmation)
R	Refresh current view
o	Configure visible columns

Context

Key	Action
p	Switch project
z	Switch zone
/	Filter resources
:	Command mode
?	Show help
q	Quit

Command Mode (:)

Command	Action
:instances	Go to VM instances
:disks	Go to persistent disks
:buckets	Go to Cloud Storage
:clusters	Go to GKE clusters
:zone us-west1-a	Switch zone
:project my-proj	Switch project
:theme <name>	Switch theme (see Themes section)
:alias <name> <resource>	Create resource alias
:q	Quit

Supported Resources

Compute Engine

• VM Instances - View, start, stop, reset, delete
• Persistent Disks - View, delete
• VPC Networks - View
• Subnets - View
• Firewall Rules - View, delete

Cloud Storage

• Buckets - View, navigate to objects
• Objects - View, download URL

Google Kubernetes Engine

• Clusters - View, navigate to node pools
• Node Pools - View

Cloud CDN / Load Balancing

• Backend Services - View, delete (shows CDN status)
• Backend Buckets - View, delete (static content CDN)
• URL Maps - View, delete (routing rules)
• HTTP/HTTPS Proxies - View, delete
• TCP/SSL/gRPC Proxies - View, delete
• Forwarding Rules - View, delete (external IPs)
• SSL Certificates - View, delete (managed & self-managed)
• Health Checks - View, delete
• Target Pools - View, delete (legacy network LB)
• SSL Policies - View, delete (TLS configuration)
• Security Policies - View, delete (Cloud Armor WAF/DDoS)
• Network Endpoint Groups - View, delete (NEGs)

Themes

tgcp includes 7 built-in themes:

Theme	Description
default	Clean, balanced colors
dracula	Dark purple-pink theme
monokai	Classic code editor colors
nord	Arctic blue-grey palette
gruvbox	Retro warm colors
solarized	Low-contrast precision
production	High-contrast red for prod awareness

Switch themes with :theme <name>:

:theme dracula
:theme production

Themes are saved per-project, so you can use a bright theme for dev and production for prod environments.

Configuration

Configuration is stored at ~/.config/tgcp/config.json:

{
  "project_id": "my-project",
  "zone": "us-central1-a",
  "last_resource": "compute-instances",
  "theme": "default",
  "project_themes": {
    "prod-project": "production",
    "dev-project": "dracula"
  },
  "aliases": {
    "vms": "compute-instances",
    "lb": "cdn-backend-services"
  },
  "ssh": {
    "use_iap": false,
    "extra_args": []
  },
  "hidden_columns": {
    "compute-instances": ["DISK R", "DISK W", "NET OUT"]
  }
}

Command-line Options

tgcp [OPTIONS]

Options:
  -p, --project <PROJECT>    GCP project ID
  -z, --zone <ZONE>          Compute zone
  -r, --readonly             Read-only mode (disable actions)
  -l, --log-level <LEVEL>    Log level [default: info]
  -h, --help                 Print help
  -V, --version              Print version

Logging

Logs are written to ~/.config/tgcp/tgcp.log. Enable debug logging:

tgcp --log-level debug

Authentication

tgcp uses Application Default Credentials (ADC):

# User credentials (recommended for local development)
gcloud auth application-default login

# Or use a service account
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Troubleshooting

"Permission denied" errors

Ensure your account has the necessary IAM permissions for the resources you're accessing (e.g., compute.instances.list).

"Authentication failed"

Refresh your credentials:

gcloud auth application-default login

Terminal rendering issues

• Ensure your terminal supports 256 colors
• Try resizing your terminal window
• Check that UTF-8 encoding is enabled

Development

See CLAUDE.md for development documentation, architecture details, and contribution guidelines.

# Run in development
cargo run

# Run tests
cargo test

# Run lints
cargo clippy

# Format code
cargo fmt

Tech Stack

• Rust - Systems programming language
• ratatui - Terminal UI framework
• tokio - Async runtime
• reqwest - HTTP client with rustls
• gcp_auth - GCP authentication

License

MIT License - see LICENSE for details.

Acknowledgments

• Based on taws - Terminal UI for AWS
• Inspired by k9s for Kubernetes
• Built with the excellent ratatui TUI framework