From 923336ff833c6b9ea48f71aec2a5a0868dd5ff78 Mon Sep 17 00:00:00 2001 From: Mathieu Poussin Date: Tue, 10 Feb 2026 17:00:28 +0100 Subject: [PATCH 1/2] Better readme --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 102 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index c463a9e..f905bb6 100644 --- a/README.md +++ b/README.md @@ -162,35 +162,114 @@ compass completion fish > ~/.config/fish/completions/compass.fish compass completion powershell | Out-String | Invoke-Expression ``` -## Quick Start +## Getting Started +### Initial Setup + +After installing `compass`, you're ready to use it immediately if you already have `gcloud` installed and authenticated. Compass uses your existing `gcloud` credentials, so there's no additional authentication needed. + +**Verify your setup:** ```bash -# Simple SSH to an instance (discovers project, zone automatically if cached) -compass gcp ssh my-instance +# Check compass is installed +compass version -# First time connecting - specify the project -compass gcp ssh my-instance --project my-gcp-project +# Check gcloud is authenticated +gcloud auth list +``` -# Look up which resources use a specific IP address -compass gcp ip lookup 192.168.0.208 +### Loading Projects + +For multi-project operations (IP lookups, instance discovery across projects, global search), you'll want to import your GCP projects into the cache: -# Import projects for multi-project operations (interactive) +**Interactive project selection:** +```bash compass gcp projects import +``` + +This command discovers all projects you have access to and presents an interactive menu. Use arrow keys to navigate, `Space` to select/deselect projects, and `Enter` to confirm. Only selected projects will be used for multi-project searches. -# Import projects matching a regex pattern (non-interactive) +**Quick import with regex:** +```bash +# Import all production projects compass gcp projects import --regex "^prod-" -# Search cached projects for instances with matching names -compass gcp search piou +# Import dev and staging projects +compass gcp projects import -r "dev|staging" +``` -# Inspect VPN gateways -compass gcp vpn list --project prod +**Why import projects?** +- Enables instance discovery without specifying `--project` every time +- Powers the global resource search across your infrastructure +- Speeds up IP lookups by caching subnet information +- Learns from your search patterns to prioritize frequently-used projects -# Launch the interactive TUI -compass interactive +### Using the Interactive TUI -# Update to the latest published release -compass update +Launch the Terminal UI for a visual, keyboard-driven experience: + +```bash +compass interactive # or: compass i +``` + +**Essential keyboard shortcuts:** + +| Key | Action | Description | +|-----|--------|-------------| +| `↑` / `↓` | Navigate | Move through the list | +| `s` | SSH | Connect to selected instance | +| `d` | Details | Show detailed information | +| `b` | Browser | Open resource in Cloud Console | +| `/` | Filter | Filter current view (AND/OR/NOT operators) | +| `Shift+S` | Search | Global search across all resource types | +| `Shift+R` | Refresh | Reload current view | +| `v` | VPN View | Switch to VPN inspection | +| `c` | CT View | Switch to connectivity tests | +| `i` | IP Lookup | Switch to IP address lookup | +| `?` | Help | Show all available shortcuts | +| `Esc` | Back/Quit | Clear filter or exit application | + +**Filter syntax:** +- `web prod` — AND: must contain both "web" AND "prod" +- `web|api` — OR: must contain "web" OR "api" +- `-dev` — NOT: must NOT contain "dev" +- Combine: `web|api prod -staging` — ("web" or "api") AND "prod" but NOT "staging" + +**In global search (`Shift+S`):** +- `Tab` — Toggle fuzzy matching (e.g., "prd" matches "production") +- Results appear progressively as they're found across 22 resource types +- Use `/` to further filter results after search completes + +### Common Commands + +Once you've set up projects, here are the most frequently used commands: + +**SSH to instances:** +```bash +# If the instance is in a cached project, just use its name +compass gcp ssh my-instance + +# First time connecting to a new instance? Specify the project +compass gcp ssh my-instance --project my-gcp-project + +# Subsequent connections remember the project, zone, and IAP preference +compass gcp ssh my-instance +``` + +Compass automatically discovers the instance's zone, determines if IAP tunneling is needed, caches the metadata for instant future connections, and learns which projects to prioritize for similar searches. + +**Search and lookup:** +```bash +# Global search across all resource types (22 types supported) +compass gcp search piou + +# Look up which resources use a specific IP address +compass gcp ip lookup 192.168.0.208 +``` + +**VPN and connectivity:** +```bash +# Inspect VPN gateways, tunnels, and BGP sessions +compass gcp vpn list --project prod # Test connectivity between instances compass gcp connectivity-test create web-to-db \ @@ -200,6 +279,12 @@ compass gcp connectivity-test create web-to-db \ --destination-port 5432 ``` +**Maintenance:** +```bash +# Update to the latest published release +compass update +``` + ## Command Examples ### SSH Connection Examples From 1831245185aebee450a5213551059af28b2460f8 Mon Sep 17 00:00:00 2001 From: Mathieu Poussin Date: Tue, 10 Feb 2026 17:01:57 +0100 Subject: [PATCH 2/2] ignore CI on md update --- .github/workflows/ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3e925af..2d80e91 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,8 +3,12 @@ name: Continuous Integration on: push: branches: [main] + paths-ignore: + - '**.md' pull_request: branches: [main] + paths-ignore: + - '**.md' permissions: contents: read