gcon

gcon

A modern terminal UI for managing Google Cloud Platform resources

---

Installation · Features · Authentication · Quick Start · Usage · Development · Contributing

Overview

gcon is a powerful, keyboard-driven terminal user interface (TUI) for managing Google Cloud Platform resources. Built with Bubble Tea and Go, it provides a fast, intuitive alternative to the GCP Console and gcloud CLI for common cloud operations.

Why gcon?

• 🚀 Fast & Efficient - Navigate your GCP resources with keyboard shortcuts, no mouse needed
• 💻 Terminal Native - Works seamlessly in any terminal, perfect for SSH sessions and remote work
• 🎨 Beautiful UI - Modern terminal interface with GCP color scheme, spinners, and status indicators
• ⚡ Async Operations - Non-blocking API calls with real-time loading indicators
• 🔍 Fuzzy Search - Quickly find projects, instances, and resources with built-in filtering
• 📊 Resource Monitoring - Real-time metrics, logs, and observability for your instances

Quick Start

1. Install gcon (see Installation below)
2. Authenticate with GCP:

   gcloud auth application-default login
   

3. Launch gcon:

   gcon
   

4. Select a project - On first launch, you'll see the project selector
5. Navigate resources - Use arrow keys or vim bindings to navigate

Installation

Homebrew (macOS & Linux)

brew install slayer/gcon/gcon

Install Script (macOS & Linux)

curl -sSL https://raw.githubusercontent.com/slayer/gcon/master/install.sh | sh

Or a specific version:

curl -sSL https://raw.githubusercontent.com/slayer/gcon/master/install.sh | sh -s -- v0.7.0

Deb / RPM (Linux)

Download .deb or .rpm packages from the latest release:

# Debian/Ubuntu
sudo dpkg -i gcon_*.deb

# RHEL/Fedora
sudo rpm -i gcon_*.rpm

From Source

go install github.com/slayer/gcon/cmd/gcon@latest

From Releases

Download the latest binary from Releases.

Features

✅ Currently Implemented

Project Management

• 🔄 Project Selector - Browse all accessible GCP projects with fuzzy search and filtering
• 🔀 Quick Project Switching - Switch between projects via command palette without losing context
• 📋 Project Metadata - View and edit project metadata and labels
• 🎯 Default Project - Automatic detection from gcloud config or environment variables

Compute Engine

• 📦 VM Instance Management

  • List all instances with status indicators (running, stopped, transitioning)
  • View detailed instance information (machine type, zones, IPs, tags, labels)
  • Start, stop, reset, suspend, and resume instances
  • Delete instances with confirmation dialogs
  • Create new instances with guided forms
  • Real-time status updates with visual indicators

• 📈 Instance Observability

  • CPU utilization with sparkline trends
  • Memory usage monitoring (requires Ops Agent)
  • Network traffic statistics (ingress/egress)
  • Disk I/O metrics
  • Instance health and uptime tracking
  • Automated performance recommendations
  • Recent error and warning logs
  • Multiple time ranges (1h, 6h, 24h, 7d, 30d)
  • Auto-refresh capability

• 💾 Persistent Disk Management

  • List all disks with details (size, type, status, attachments)
  • View disk details and usage information
  • Create new disks from scratch or from snapshots
  • Delete disks with safety confirmations
  • Link navigation to attached instances

• 📸 Snapshot Management

  • List all disk snapshots
  • View snapshot details and source disks
  • Create snapshots from existing disks
  • Navigate to source disks from snapshots

• 🖼️ Image Management

  • List all disk images (custom and public)
  • View image details and properties
  • Create images from disks or snapshots
  • Support for various image families

• 🏷️ Metadata & Labels

  • View and edit instance metadata
  • Manage labels on instances and disks
  • Bulk label operations

Cloud Storage

• 🪣 Bucket Management

  • List all Cloud Storage buckets
  • View bucket details (location, storage class, access control)
  • Create new buckets with comprehensive options:
    • Location type selection (region/dual-region/multi-region)
    • Storage class selection (STANDARD/NEARLINE/COLDLINE/ARCHIVE)
    • Access control settings (uniform/fine-grained)
    • Data protection (versioning, retention, soft delete)
    • Labels and CMEK encryption support

• 📁 Object Browser

  • Navigate bucket contents with folder structure
  • Upload files and folders
  • Download individual files or entire folders
  • Delete objects with confirmation
  • View object details and metadata
  • Pagination for large buckets

Cloud SQL

• 🗄️ SQL Instance Management
  • List all Cloud SQL instances with version, state, region, tier, and IP
  • View instance details with 3 tabs (Details/Databases/Backups)
  • Lifecycle actions: start, stop, restart, delete (with type-to-confirm)
  • State display reconciling activationPolicy with instance state
  • List databases per instance
  • List backup runs and create on-demand backups

VPC Networking

• 🌐 VPC Network Management

  • List all VPC networks with subnet counts and routing mode
  • View network details (MTU, routing mode, subnet mode, peerings)
  • IPv6 configuration and ULA range information
  • Browse subnets within each network with IP ranges and regions
  • Navigate between related network resources

• 🔥 Firewall Rules

  • List all firewall rules with direction, priority, action, protocols, and status
  • View detailed rule information (allowed/denied entries, source/destination ranges, tags)
  • Enable and disable firewall rules
  • Delete rules with type-to-confirm dialogs
  • Navigate to associated VPC networks from rule details

IAM & Admin

• 🔐 Service Account Management

  • List service accounts with status indicators (active/disabled)
  • View details with keys tab
  • Create, delete, enable/disable service accounts
  • Key management (create/delete) with JSON download on creation

• 📜 IAM Policy Bindings

  • View bindings by member or by role with tab navigation
  • Add/remove members to/from role bindings
  • Detail overlay for viewing member's roles or role's members
  • Safe etag-based read-modify-write with conflict retry

• 🎭 Custom Roles (read-only)

  • List custom roles with details and permissions tabs

Cloud Run

• 🚀 Service Management

  • List services across all regions with status, URL, latest revision
  • Service details with 4 tabs (Details/Revisions/YAML/Observability)
  • Traffic split editing (validates percentages sum to 100)
  • Edit existing service configuration with diff preview before deploy
  • Create new services with full form (container, scaling, networking, security)
  • Delete services with type-to-confirm

• 📈 Cloud Run Observability

  • Request count, latency (p50/p95/p99), error rate (4xx/5xx) charts
  • CPU utilization, billable instance time, instance count charts
  • Filterable log viewer (INFO/WARNING/ERROR severity toggles)
  • Time range selection and auto-refresh

Cloud Logging

• 📋 Logs Explorer
  • LQL query input with filter bar
  • Quick filters (Resources, Log Names, Severities) with lazy-loaded options and search
  • Tab cycling between entries, filters, query input, and time range
  • Sparkline histogram for log density over time
  • Expandable log entries with severity color coding
  • Logfmt and protobuf key:value syntax colorization (toggle with c)
  • Field-level cursor with filter-by-field (Enter on expanded field)
  • Infinite scroll pagination (200 entries per page)
  • Tail mode (live streaming, 15s polling)
  • Time range selection (1h/6h/24h/7d/30d)
  • Line wrapping toggle (w key)
  • Open in $PAGER with p key (respects color toggle)
  • Export to TXT/CSV/JSONL via action menu
  • ANSI-aware truncation and wrapping (preserves existing log colors)

User Interface & Navigation

• 🎯 Command Palette - Quick access to all actions with fuzzy search (: or Ctrl+K)
• 📂 Sidebar Navigation - Collapsible sidebar with auto-hide mode and resource categories
• 🍞 Breadcrumb Navigation - Always know where you are in the resource hierarchy
• 📜 Recent Items - Quick access to recently viewed resources
• ⌨️ Keyboard Shortcuts - Vim-style navigation throughout the interface
• 🔄 Context Menus - Action menus for resource-specific operations
• ⚡ Loading States - Spinners and progress indicators for all async operations
• ❌ Error Handling - Inline error display with retry options
• 📊 Status Bar - Real-time status updates and operation feedback

🚧 Planned Features

The following features are planned for future releases:

• SSH Integration - Direct SSH access to instances via gcloud
• Resource Caching - Local caching layer for faster repeated queries
• Google Kubernetes Engine (GKE)
  • Cluster listing and details
  • Node pool management
  • Workload viewing
• Cloud Functions - Function deployment and monitoring
• Subnets - Standalone subnet list and management
• Load Balancers - Load balancer configuration and health
• Cost Explorer - Resource cost analysis and budgets

Authentication

gcon uses Google Cloud's Application Default Credentials (ADC). Choose one of these methods:

Option 1: User Credentials (requires gcloud CLI)

gcloud auth application-default login

Option 2: Service Account Key

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Option 3: Workload Identity (GCP environments)

When running on GKE, Cloud Run, or GCE, authentication is automatic via the attached service account.

Configuration

gcon respects standard GCP SDK environment variables:

Variable	Description
CLOUDSDK_CORE_PROJECT	Default project
CLOUDSDK_COMPUTE_ZONE	Default zone
CLOUDSDK_COMPUTE_REGION	Default region
CLOUDSDK_CORE_ACCOUNT	Default account
CLOUDSDK_ACTIVE_CONFIG_NAME	gcloud config to use
GOOGLE_APPLICATION_CREDENTIALS	Path to service account JSON
NO_COLOR	Disable colored output
HTTP_PROXY / HTTPS_PROXY	Proxy settings

If gcloud CLI is installed, gcon also reads defaults from ~/.config/gcloud/.

Usage

Basic Navigation

Once launched, gcon presents an intuitive interface with:

• Sidebar (left) - Quick access to resource categories
• Main View (center) - Current resource list or details
• Status Bar (bottom) - Current operation status and key hints
• Breadcrumbs (top) - Your current location in the resource hierarchy

Key Bindings

Global Shortcuts

Key	Action	Description
: / Ctrl+K	Command Palette	Quick access to all commands with fuzzy search
Ctrl+C or q	Quit	Exit the application
Esc	Go Back	Return to previous view
?	Help	Show context-sensitive help
r	Refresh	Reload current view
.	Action Menu	Open context-sensitive action menu
[	Focus Sidebar	Move focus to sidebar (expands if auto-hidden)
]	Focus Content	Move focus to main content (collapses if auto-hide)
{	Pin Sidebar	Toggle auto-hide / always-open mode

Navigation

Key	Action	Description
j or ↓	Move Down	Move cursor down in lists
k or ↑	Move Up	Move cursor up in lists
h or ←	Move Left	Move left in horizontal navigation
l or →	Move Right	Move right in horizontal navigation
g	Go to Top	Jump to first item
G	Go to Bottom	Jump to last item
Ctrl+D	Page Down	Scroll down one page
Ctrl+U	Page Up	Scroll up one page
Enter	Select	Select current item or confirm action
/	Search/Filter	Filter current list
Tab	Next Section	Move to next section (in details views)
Shift+Tab	Previous Section	Move to previous section

Compute Engine - Instances

Key	Action	Description
Enter	View Details	Show detailed instance information
s	Start	Start a stopped instance
x	Stop	Stop a running instance
r	Reset	Reset (reboot) an instance
p	Suspend	Suspend a running instance
R	Resume	Resume a suspended instance
D	Delete	Delete instance (with confirmation)
c	Create	Create a new instance
l	Edit Labels	Open label editor
m	Metadata	View/edit instance metadata
o	Observability	View metrics and logs

Compute Engine - Disks

Key	Action	Description
Enter	View Details	Show detailed disk information
c	Create Disk	Create a new persistent disk
D	Delete	Delete disk (with confirmation)
s	Create Snapshot	Create a snapshot from this disk
l	Edit Labels	Manage disk labels

Compute Engine - Snapshots

Key	Action	Description
Enter	View Details	Show snapshot details
c	Create Snapshot	Create a new snapshot
D	Delete	Delete snapshot (with confirmation)
d	View Source Disk	Navigate to the source disk

Compute Engine - Images

Key	Action	Description
Enter	View Details	Show image details
c	Create Image	Create a new image
D	Delete	Delete custom image (with confirmation)

Cloud Storage - Buckets

Key	Action	Description
Enter	Browse Contents	Open bucket and view objects
c	Create Bucket	Create a new bucket with guided form
D	Delete	Delete bucket (must be empty)
/	Filter	Filter buckets by name
r	Refresh	Reload bucket list

Cloud Storage - Objects

Key	Action	Description
Enter	Open/View	Open folder or view file details
u	Upload	Upload files to current folder
d	Download	Download selected file or folder
D	Delete	Delete object (with confirmation)
n	Next Page	Navigate to next page
p	Previous Page	Navigate to previous page
Backspace	Go Up	Go to parent folder

VPC Networks

Key	Action	Description
Enter	View Details	Show detailed network information
/	Filter	Filter networks by name
r	Refresh	Reload network list
Esc	Go Back	Return to previous view

VPC Network Details

Key	Action	Description
.	Action Menu	Open context-sensitive action menu
r	Refresh	Refresh network details and subnets
Tab	Switch Focus	Switch focus between tabs, links, and content
h/l or 1/2	Switch Tabs	Switch between Details and Subnets tabs
j/k or ↓/↑	Navigate	Navigate subnet links or scroll content
Esc	Go Back	Return to networks list

Firewall Rules

Key	Action	Description
Enter	View Details	Show detailed firewall rule information
.	Action Menu	Open context-sensitive action menu
t	Toggle	Enable or disable firewall rule
D	Delete	Delete firewall rule (with confirmation)
/	Filter	Filter rules by name, direction, network
r	Refresh	Reload firewall rules list
Esc	Go Back	Return to previous view

Firewall Rule Details

Key	Action	Description
.	Action Menu	Open context-sensitive action menu
t	Toggle	Enable or disable firewall rule
D	Delete	Delete firewall rule (with confirmation)
r	Refresh	Refresh rule details
Tab	Switch Focus	Switch focus between tabs, links, and content
h/l or 1/2	Switch Tabs	Switch between Details and Rules tabs
Enter	Navigate	Navigate to associated VPC network
Esc	Go Back	Return to firewall rules list

Cloud SQL - Instances

Key	Action	Description
Enter	View Details	Show instance details with tabs
.	Action Menu	Open context-sensitive action menu
S	Sort Menu	Open column sort menu
s	Start	Start a stopped instance
x	Stop	Stop a running instance
R	Restart	Restart an instance
D	Delete	Delete instance (with type-to-confirm)
/	Filter	Filter instances
r	Refresh	Reload instance list
Esc	Go Back	Return to previous view

Cloud SQL - Instance Details

Key	Action	Description
.	Action Menu	Open context-sensitive action menu
s	Start	Start instance (if stopped)
x	Stop	Stop instance (if running)
R	Restart	Restart instance
D	Delete	Delete instance (with type-to-confirm)
b	Create Backup	Create on-demand backup (Backups tab)
r	Refresh	Refresh all tabs
Tab	Switch Focus	Switch focus between tabs and content
h/l or 1/2/3	Switch Tabs	Switch between Details, Databases, and Backups tabs
j/k or ↓/↑	Scroll	Scroll content
Esc	Go Back	Return to instances list

IAM Policy

Key	Action	Description
Enter	Details	Open member/role detail overlay
a	Add	Add member to role or role to member
.	Action Menu	Open context-sensitive action menu
S	Sort Menu	Open column sort menu
/	Filter	Filter by role, member, or condition
r	Refresh	Reload IAM policy
Tab	Switch Focus	Switch focus between tabs and table
h/l or 1/2	Switch Tabs	Switch between By Member and By Role tabs
Esc	Close/Back	Close overlay, clear filter, or go back

Key	Action	Description
j/k or ↓/↑	Navigate	Navigate items in the overlay
a	Add	Add member or role
d	Remove	Remove selected item (with confirmation)
Esc	Close	Close overlay

Cloud Run Services

Key	Action	Description
Enter	View Details	Show service details
.	Action Menu	Open context-sensitive action menu
c	Create	Create a new service
D	Delete	Delete service (with type-to-confirm)
e	Edit	Edit service configuration
/	Filter	Filter services
r	Refresh	Reload service list

Logs Explorer

Key	Action	Description
/	Focus Query	Focus the LQL query input
Enter	Run/Expand	Run query (input) / Expand entry / Filter by field
Esc	Blur/Collapse	Blur input / Collapse entry / Close filter / Go back
Tab	Cycle Focus	Cycle focus (entries / filters / query / time range)
Shift+Tab	Cycle Back	Cycle focus backwards
j/k or ↓/↑	Navigate	Navigate log entries
→ or Enter	Expand	Expand entry / Enter field navigation
←	Collapse	Collapse entry / Exit field navigation
PgUp/PgDn	Page	Page up/down through entries
E	Expand All	Expand all visible entries
C	Collapse All	Collapse all entries
w	Toggle Wrap	Toggle line wrapping
c	Toggle Colors	Toggle logfmt/protobuf colorization
1-5	Time Range	Set time range (1h/6h/24h/7d/30d)
f	Tail Mode	Toggle tail mode (15s polling)
r	Refresh	Re-run query
R	Resources	Open resource type filter
L	Log Names	Open log name filter
V	Severities	Open severity filter
p	Pager	Open entries in $PAGER
.	Action Menu	Export to TXT/CSV/JSONL

Logs Explorer - Filter Dropdown

Key	Action	Description
j/k or ↓/↑	Navigate	Navigate filter options
PgUp/PgDn	Page	Page up/down through options
Space/Tab/Enter	Toggle	Toggle option selection
/	Search	Search within filter options
Esc	Apply/Close	Apply selection and close

Label & Metadata Editors

Key	Action	Description
a	Add	Add new label or metadata entry
e or Enter	Edit	Edit selected entry
d or x	Delete	Delete selected entry
Ctrl+S	Save	Save all changes
Esc	Cancel	Cancel without saving
Tab	Next Field	Move to next input field
Shift+Tab	Previous Field	Move to previous input field

Form Navigation

Key	Action	Description
Tab	Next Field	Move to next form field
Shift+Tab	Previous Field	Move to previous form field
Space	Toggle	Toggle checkbox/radio options
Enter	Select/Submit	Select dropdown option or submit form
Esc	Cancel	Cancel form and return
Ctrl+S	Submit	Submit form (alternative to Enter)

Development

Building from Source

# Clone the repository
git clone https://github.com/slayer/gcon.git
cd gcon

# Build the binary
make build

# Run directly
make run

# Run with race detector (for development)
make dev

Running Tests

# Run all tests
make test

# Run tests with coverage
go test -cover ./...

# Run tests with verbose output
go test -v ./...

Code Quality

# Install golangci-lint
make install-lint

# Run linter
make lint

# Run linter with auto-fix
make lint-fix

Project Structure

gcon/
├── cmd/gcon/              # Application entry point
├── internal/
│   ├── gcp/               # GCP API clients and abstractions
│   │   ├── client.go      # Base client with authentication
│   │   ├── compute.go     # Compute Engine operations
│   │   ├── storage.go     # Cloud Storage operations
│   │   ├── monitoring.go  # Cloud Monitoring (metrics)
│   │   ├── logging.go     # Cloud Logging (entries, filters, histogram)
│   │   ├── metadata.go    # Metadata and labels
│   │   ├── networks.go    # VPC Networks and subnets
│   │   ├── firewalls.go   # Firewall rules
│   │   ├── sql.go         # Cloud SQL instances
│   │   ├── iam.go         # IAM policies, service accounts
│   │   └── cloudrun.go    # Cloud Run services
│   └── ui/
│       ├── app.go         # Main application controller
│       ├── keys.go        # Global key bindings
│       ├── styles.go      # UI styling (Lip Gloss)
│       ├── components/    # Reusable UI components
│       │   ├── spinner.go
│       │   ├── statusbar.go
│       │   ├── sidebar.go
│       │   ├── table.go
│       │   └── logviewer/ # Log entry list with expand/collapse
│       └── views/         # Feature-specific views
│           ├── projects.go
│           ├── instances.go
│           ├── disks.go
│           ├── snapshots.go
│           ├── images.go
│           ├── buckets.go
│           ├── objects.go
│           ├── networks.go
│           ├── network_details.go
│           ├── firewalls.go
│           ├── firewall_details.go
│           ├── sql_instances.go
│           ├── sql_instance_details.go
│           ├── cloudrun_services.go
│           └── logs.go    # Cloud Logging Explorer
├── doc/                   # Feature documentation
├── Makefile
└── README.md

Troubleshooting

Authentication Issues

Problem: Error: unable to find default credentials

Solution: Run authentication command:

gcloud auth application-default login

Or set up a service account:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

Permission Issues

Problem: Error: Permission denied when listing resources

Solution: Ensure your account has the required IAM roles:

• Viewer role for read-only access
• Compute Admin for managing Compute Engine resources
• Storage Admin for managing Cloud Storage

Grant roles via the GCP Console or using gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:EMAIL" \
  --role="roles/compute.admin"

Network/Proxy Issues

Problem: Error: connection timeout when calling GCP APIs

Solution: Configure proxy settings:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

Or bypass proxy for GCP APIs:

export NO_PROXY=googleapis.com,google.com

Terminal Display Issues

Problem: Colors or formatting look broken

Solution:

1. Ensure your terminal supports 256 colors or truecolor
2. Try disabling colors:

   NO_COLOR=1 gcon
   

3. Update your terminal emulator to a modern version

Performance Issues

Problem: Slow loading or high memory usage

Solution:

• Use project filtering to limit scope
• Reduce the number of resources in lists
• Check your internet connection to GCP APIs
• Consider using a service account with minimal permissions

Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository on GitHub
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following the code style guidelines
4. Run tests: make test
5. Run linter: make lint
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to your fork: git push origin feature/amazing-feature
8. Open a Pull Request

Code Style

• Follow Go best practices and idioms
• Use gofmt for formatting (included in make lint)
• Write meaningful commit messages
• Add tests for new features
• Update documentation when needed
• Keep functions small and focused (<50 lines)
• Use descriptive variable names

Development Guidelines

• See CLAUDE.md for detailed architecture documentation
• Use the Bubble Tea patterns described in the project
• Follow existing UI/UX patterns for consistency
• Add keyboard shortcuts for all new actions
• Show loading spinners for async operations
• Handle errors gracefully with retry options

Acknowledgments

• Built with Bubble Tea - A powerful TUI framework
• Styled with Lip Gloss - Style definitions for terminal output
• Uses Bubbles - Common TUI components
• Inspired by k9s and lazygit

License

MIT License - see LICENSE file for details

Support

• Issues: Report bugs or request features on GitHub Issues
• Discussions: Join conversations on GitHub Discussions
• Documentation: See CLAUDE.md for technical documentation

---

Made with ❤️ for the Google Cloud community