From 545d3570f8eba1aa663ee26d15ee5d0c55df7a30 Mon Sep 17 00:00:00 2001 From: Levente Csoke Date: Mon, 30 Mar 2026 07:49:41 +0200 Subject: [PATCH 1/3] docs: add gcpath agent skill for AI agent consumption Adds a skills/gcpath/ directory following the Agent Skills spec (agentskills.io), enabling agents to install and use gcpath via: bunx skills add github:tardigrde/gcpath --skill gcpath Includes SKILL.md (when-to-use guidance, all commands with examples, common workflows, gotchas) and references/commands.md (compact flag reference per command). Co-Authored-By: Claude Sonnet 4.6 --- skills/gcpath/SKILL.md | 257 +++++++++++++++++++++++++++ skills/gcpath/references/commands.md | 243 +++++++++++++++++++++++++ 2 files changed, 500 insertions(+) create mode 100644 skills/gcpath/SKILL.md create mode 100644 skills/gcpath/references/commands.md diff --git a/skills/gcpath/SKILL.md b/skills/gcpath/SKILL.md new file mode 100644 index 0000000..d60d939 --- /dev/null +++ b/skills/gcpath/SKILL.md @@ -0,0 +1,257 @@ +--- +name: gcpath +description: > + Use this skill when you need to navigate, query, or resolve resources in a + Google Cloud Platform (GCP) organization hierarchy — listing folders or + projects under a resource, converting between resource names (e.g. + folders/12345) and human-readable paths (e.g. //example.com/dept/team), + searching resources by display name, showing ancestry chains, or generating + hierarchy diagrams. Do NOT use for IAM policy, billing, cost analysis, + Kubernetes, or Compute Engine resources. +--- + +# gcpath + +A CLI for querying GCP resource hierarchy paths. It translates between GCP +resource names (`folders/12345`) and human-readable paths (`//example.com/dept/team`) +and lets you explore the org → folder → project tree. + +## When to Use + +**Use gcpath when asked to:** + +- List what folders or projects are inside a GCP folder or organization +- Find the hierarchy path of a project or folder +- Convert a human-readable path to a GCP resource name (for use in `gcloud`, Terraform, etc.) +- Search for a project or folder by display name +- Show the ancestry chain of any resource +- Generate a Mermaid or D2 diagram of the resource hierarchy +- Count folders and projects under a scope + +**Do NOT use gcpath for:** + +- IAM policy management (`gcloud projects get-iam-policy` is the right tool) +- Billing or cost queries +- Compute, GKE, Cloud Run, or other product-level resources +- Resource creation or modification (gcpath is read-only) + +## Installation + +```bash +pip install gcpath +# or +uv add gcpath +``` + +**Authentication** — gcpath uses Application Default Credentials. Authenticate with: + +```bash +gcloud auth application-default login +``` + +Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file. + +**Required IAM roles** (on the org or target scope): + +- `roles/resourcemanager.organizationViewer` +- `roles/resourcemanager.folderViewer` +- `roles/resourcemanager.projectViewer` +- Or: `roles/cloudasset.viewer` (Cloud Asset API mode, the default) + +## Core Concepts + +- **Resource names**: `organizations/123`, `folders/456`, `projects/789` or `projects/my-project-id` +- **Paths**: `//example.com/Department/Team` — double-slash prefix, then org domain, then slash-separated display names +- **Organizationless projects**: shown with `//_/` prefix (no org parent) +- **Entrypoint**: a default root resource to scope all commands to (set once, used implicitly) + +## Commands + +### List children: `ls` + +```bash +gcpath ls # all orgs/projects you have access to +gcpath ls folders/123 # direct children of a folder +gcpath ls folders/123 -R # all descendants, recursively +gcpath ls folders/123 -R -L 2 # recursive, max 2 levels deep +gcpath ls folders/123 -l # long format: show resource names alongside paths +gcpath ls folders/123 --type project # only projects +gcpath ls folders/123 --label env=production # filter by GCP label +gcpath ls folders/123 --tag cost-center=eng # filter by GCP tag +gcpath ls folders/123 --show-labels --show-tags # show labels/tags in output +``` + +### Tree view: `tree` + +```bash +gcpath tree # full hierarchy tree +gcpath tree folders/123 # subtree from a folder +gcpath tree folders/123 -L 3 # limit depth +gcpath tree folders/123 -i # show resource names alongside display names +gcpath tree folders/123 --type project # only show projects +gcpath tree -y # skip confirmation for large loads +``` + +### Diagram: `diagram` + +```bash +gcpath diagram # Mermaid diagram of full hierarchy +gcpath diagram folders/123 # diagram of a subtree +gcpath diagram -f d2 # D2 format instead of Mermaid +gcpath diagram -o hierarchy.mmd # write to file +gcpath diagram folders/123 -L 2 # limit depth +``` + +### Statistics: `stats` + +```bash +gcpath stats # count orgs, folders, projects globally +gcpath stats folders/123 # count within a folder subtree +gcpath stats organizations/456 +``` + +### Resolve path → resource name: `name` + +```bash +gcpath name //example.com/Department/Team +gcpath name //example.com/Department/Team --id # print only the numeric ID +gcpath name //example.com/Dept/A //example.com/Dept/B # multiple paths +``` + +### Resolve resource name → path: `path` + +```bash +gcpath path folders/123 +gcpath path projects/my-project +gcpath path folders/123 folders/456 # multiple resources +``` + +### Search by display name: `find` + +```bash +gcpath find "data-*" # glob pattern, case-insensitive +gcpath find "*team*" folders/123 # scoped to a subtree +gcpath find "prod-*" --type project +gcpath find "*" --label env=production # find all labeled resources +``` + +### Ancestry chain: `ancestors` + +```bash +gcpath ancestors projects/my-project +gcpath ancestors folders/123 +``` + +### Cache management + +```bash +gcpath cache status # show cache age, size, scope +gcpath cache clear # force next run to re-fetch from GCP +``` + +### Configuration + +```bash +gcpath config set-entrypoint folders/123 # always scope to this folder by default +gcpath config show # display current config +gcpath config clear-entrypoint +``` + +## Global Flags + +These apply to any command: + +| Flag | Short | Description | +|------|-------|-------------| +| `--entrypoint RESOURCE` | `-e` | Default scope for this invocation | +| `--json` | | Output as JSON | +| `--yaml` | | Output as YAML | +| `--force-refresh` | `-F` | Bypass cache, re-fetch from GCP API | +| `--no-use-asset-api` | `-U` | Use Resource Manager API instead of Cloud Asset API | +| `--debug` | | Enable debug logging | + +## Common Workflows + +### 1. Find which folder a project lives in + +```bash +gcpath ancestors projects/my-project +# or +gcpath path projects/my-project +``` + +### 2. List all projects in a folder + +```bash +gcpath ls folders/123 -R --type project +``` + +### 3. Get the resource name for a path (e.g. to use in gcloud) + +```bash +gcpath name //example.com/Engineering/Backend +# → folders/456789 +gcloud projects list --filter="parent.id=456789" +``` + +### 4. Search for a project by display name + +```bash +gcpath find "*payments*" --type project +``` + +### 5. Explore a subtree visually + +```bash +gcpath tree folders/123 -L 3 -i +``` + +### 6. Generate a diagram for docs + +```bash +gcpath diagram folders/123 -f mermaid -o team-hierarchy.mmd +``` + +### 7. Filter resources by label + +```bash +gcpath ls --label env=production --label team=platform -R +``` + +## Output Formats + +By default, output is formatted for terminal readability (using Rich). For +programmatic use: + +```bash +gcpath ls folders/123 --json | jq '.[] | .path' +gcpath tree folders/123 --yaml +gcpath ancestors projects/my-project --json +``` + +## API Modes + +| Mode | Flag | Speed | Permissions needed | +|------|------|-------|--------------------| +| Cloud Asset API | (default) | Fast — bulk SQL queries | `roles/cloudasset.viewer` | +| Resource Manager | `-U` | Slower — iterative paging | `roles/resourcemanager.*Viewer` | + +Use `-U` if the Cloud Asset API is not enabled in the project or if you lack the Asset Viewer role. + +## Caching + +gcpath caches hierarchy data locally to avoid repeated API calls. The cache is +scoped to the resource used. Use `-F` / `--force-refresh` to bypass it, or +`gcpath cache clear` to wipe it. + +## Gotchas + +- `tree`, `diagram`, `stats` do not support starting from a project (projects are leaf nodes). +- Organizationless projects appear under `//_/` in paths. +- `--label` and `--tag` filters are ANDed together when repeated. +- `gcpath path` resolves without loading the full hierarchy (it uses the GCP ancestry API directly) — it's fast even without cache. +- Scoped loads (`gcpath ls folders/123`) are faster and not cached by default unless `folders/123` is also the configured entrypoint. + +## Reference + +See [`references/commands.md`](references/commands.md) for a compact flag reference per command. diff --git a/skills/gcpath/references/commands.md b/skills/gcpath/references/commands.md new file mode 100644 index 0000000..c0e7de7 --- /dev/null +++ b/skills/gcpath/references/commands.md @@ -0,0 +1,243 @@ +# gcpath Command Reference + +Quick reference for all gcpath commands and flags. + +## Global Flags + +Apply to every command (place before the subcommand): + +| Flag | Short | Default | Description | +|------|-------|---------|-------------| +| `--entrypoint RESOURCE` | `-e` | config/none | Scope all commands to this resource | +| `--json` | | false | JSON output | +| `--yaml` | | false | YAML output | +| `--use-asset-api / --no-use-asset-api` | `-u / -U` | true (asset) | API backend | +| `--debug` | | false | Debug logging | + +--- + +## `ls [RESOURCE]` + +List direct children (or descendants with `-R`) of a resource. + +| Flag | Short | Description | +|------|-------|-------------| +| `--long` | `-l` | Show resource names alongside paths | +| `--recursive` | `-R` | List all descendants | +| `--level N` | `-L N` | Max depth (requires `-R`) | +| `--type TYPE` | `-t` | Filter: `folder`, `project`, `organization` | +| `--show-labels` | | Show GCP labels column | +| `--show-tags` | | Show GCP tags column | +| `--label KEY=VALUE` | | Filter by label (repeatable, ANDed) | +| `--tag KEY=VALUE` | | Filter by tag (repeatable, ANDed) | +| `--force-refresh` | `-F` | Bypass cache | + +**Examples:** + +``` +gcpath ls +gcpath ls folders/123 +gcpath ls folders/123 -R -L 2 --type project +gcpath ls -R --label env=prod --show-labels --json +``` + +--- + +## `tree [RESOURCE]` + +Display resource hierarchy as an interactive tree. + +| Flag | Short | Description | +|------|-------|-------------| +| `--level N` | `-L N` | Max display depth | +| `--ids` | `-i` | Show resource names next to display names | +| `--type TYPE` | `-t` | Filter: `folder`, `project` | +| `--yes` | `-y` | Skip confirmation for large unscoped loads | +| `--show-labels` | | Show labels in tree nodes | +| `--show-tags` | | Show tags in tree nodes | +| `--label KEY=VALUE` | | Filter by label (repeatable, ANDed) | +| `--tag KEY=VALUE` | | Filter by tag (repeatable, ANDed) | +| `--force-refresh` | `-F` | Bypass cache | + +**Examples:** + +``` +gcpath tree +gcpath tree folders/123 -L 3 -i +gcpath tree --type project --json +``` + +--- + +## `diagram [RESOURCE]` + +Generate a Mermaid or D2 diagram of the hierarchy. + +| Flag | Short | Description | +|------|-------|-------------| +| `--format FORMAT` | `-f` | `mermaid` (default) or `d2` | +| `--level N` | `-L N` | Max display depth | +| `--ids` | `-i` | Show resource names in node labels | +| `--output FILE` | `-o` | Write to file instead of stdout | +| `--yes` | `-y` | Skip confirmation | +| `--force-refresh` | `-F` | Bypass cache | + +**Examples:** + +``` +gcpath diagram folders/123 +gcpath diagram -f d2 -o org.d2 +gcpath diagram folders/123 -L 2 --ids +``` + +--- + +## `stats [RESOURCE]` + +Count organizations, folders, and projects in scope. Resource must be `organizations/...` or `folders/...`. + +| Flag | Short | Description | +|------|-------|-------------| +| `--force-refresh` | `-F` | Bypass cache | + +**Examples:** + +``` +gcpath stats +gcpath stats folders/123 +gcpath stats organizations/456 +``` + +--- + +## `name PATH [PATH ...]` + +Convert human-readable path(s) to GCP resource name(s). + +| Flag | Short | Description | +|------|-------|-------------| +| `--id` | | Print only the numeric ID (not the full resource name) | +| `--force-refresh` | `-F` | Bypass cache | + +**Examples:** + +``` +gcpath name //example.com/Engineering/Backend +gcpath name //example.com/Dept/Team --id +gcpath name //a.com/X //a.com/Y --json +``` + +--- + +## `path RESOURCE [RESOURCE ...]` + +Convert GCP resource name(s) to human-readable path(s). Does not load full hierarchy — resolves via GCP ancestry API directly. + +No extra flags (uses global `--json` / `--yaml`). + +**Examples:** + +``` +gcpath path folders/123 +gcpath path projects/my-project +gcpath path folders/123 folders/456 --json +``` + +--- + +## `find PATTERN [RESOURCE]` + +Search resources by display name glob pattern (case-insensitive). Supports `*` and `?`. + +| Flag | Short | Description | +|------|-------|-------------| +| `--type TYPE` | `-t` | Filter: `folder`, `project`, `organization` | +| `--label KEY=VALUE` | | Filter by label (repeatable, ANDed) | +| `--tag KEY=VALUE` | | Filter by tag (repeatable, ANDed) | +| `--force-refresh` | `-F` | Bypass cache | + +**Examples:** + +``` +gcpath find "*payments*" +gcpath find "prod-*" --type project +gcpath find "*" folders/123 --label env=staging +gcpath find "data-*" --json +``` + +--- + +## `ancestors RESOURCE` + +Show the full ancestry chain from a resource up to the organization root. Works for `organizations/...`, `folders/...`, and `projects/...`. + +No extra flags (uses global `--json` / `--yaml`). + +**Output columns:** Resource Name, Display Name, Type + +**Examples:** + +``` +gcpath ancestors projects/my-project +gcpath ancestors folders/123 --json +``` + +--- + +## `cache status` + +Show cache age, size, scope, and resource counts. + +No flags. + +--- + +## `cache clear` + +Delete the local cache file, forcing next run to re-fetch from GCP. + +No flags. + +--- + +## `config set-entrypoint RESOURCE` + +Set a persistent default entrypoint. Subsequent commands will scope to this resource unless overridden with `-e`. + +**Example:** + +``` +gcpath config set-entrypoint folders/123 +``` + +--- + +## `config show` + +Display current configuration and config file location. + +--- + +## `config clear-entrypoint` + +Remove the configured default entrypoint. + +--- + +## Resource Name Formats + +| Resource | Format | Example | +|----------|--------|---------| +| Organization | `organizations/ID` | `organizations/123456789` | +| Folder | `folders/ID` | `folders/987654321` | +| Project (by number) | `projects/NUMBER` | `projects/111222333` | +| Project (by ID) | `projects/PROJECT-ID` | `projects/my-project` | + +## Path Format + +``` +//DOMAIN/SEGMENT/SEGMENT/... +``` + +- `//example.com/Engineering/Backend/Services` +- `//_/OrphanedProject` (organizationless) From a3e354e034f8745b30461b329c95dc411a44cb11 Mon Sep 17 00:00:00 2001 From: Levente Csoke Date: Mon, 30 Mar 2026 08:12:18 +0200 Subject: [PATCH 2/3] docs: add Agent Skill section to README Adds a dedicated section explaining the bundled agent skill and how to install it via bunx/npx, plus a one-liner callout in the "Why use gcpath" bullet list. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index 72212f6..c141a46 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ It helps you translate between GCP resource names (e.g., `folders/12345`) and hu - you can stay in the terminal for quick resource hierarchy lookups - no need to learn the complex `gcloud` interface - look-up only commands, so coding agents can't do harm using it +- installable as an [Agent Skill](#agent-skill) so AI agents know how to use it ## Features @@ -478,6 +479,27 @@ except GCPathError as e: | `PathParsingError` | Raised when a path string cannot be parsed. | | `path_escape()` | URL-encodes a display name for safe use in paths. | +## Agent Skill + +gcpath ships with an [Agent Skills](https://agentskills.io) definition so AI agents (Claude, Codex, etc.) can discover and use it without extra setup. + +Install the skill into your agent environment: + +```bash +bunx skills add github:tardigrde/gcpath --skill gcpath +# or +npx skills add github:tardigrde/gcpath --skill gcpath +``` + +The skill teaches the agent: + +- when to reach for `gcpath` vs other GCP tools +- all commands, flags, and output formats +- common workflows (ancestry lookup, scoped listing, path ↔ name conversion) +- gotchas (organizationless projects, caching behaviour, API modes) + +See [`skills/gcpath/SKILL.md`](skills/gcpath/SKILL.md) for the full skill definition and [`skills/gcpath/references/commands.md`](skills/gcpath/references/commands.md) for the compact command reference. + ## Acknowledgments Thanks for [xebia/gcp-path](https://github.com/xebia/gcp-path) for the inspiration! From c9e7b2be11f3852491d57b1a24a8522a7948dd8d Mon Sep 17 00:00:00 2001 From: Levente Csoke Date: Mon, 30 Mar 2026 08:29:41 +0200 Subject: [PATCH 3/3] docs(skill): enrich frontmatter and trim body per Agent Skills spec - Add allowed-tools: Bash(gcpath:*) Bash(uvx gcpath:*) - Add compatibility, license, and metadata fields - Trim SKILL.md from 258 to 143 lines: collapse verbose commands section into common workflows + key flags table, move full flag reference to references/commands.md with explicit load trigger - Keep gotchas inline per best-practices guidance Co-Authored-By: Claude Sonnet 4.6 --- skills/gcpath/SKILL.md | 222 ++++++++++------------------------------- 1 file changed, 54 insertions(+), 168 deletions(-) diff --git a/skills/gcpath/SKILL.md b/skills/gcpath/SKILL.md index d60d939..b7edd92 100644 --- a/skills/gcpath/SKILL.md +++ b/skills/gcpath/SKILL.md @@ -8,19 +8,29 @@ description: > searching resources by display name, showing ancestry chains, or generating hierarchy diagrams. Do NOT use for IAM policy, billing, cost analysis, Kubernetes, or Compute Engine resources. +license: MIT +compatibility: > + Requires gcpath CLI (pip install gcpath or uvx gcpath) and GCP Application + Default Credentials (gcloud auth application-default login or + GOOGLE_APPLICATION_CREDENTIALS env var). +allowed-tools: Bash(gcpath:*) Bash(uvx gcpath:*) +metadata: + author: tardigrde + repository: https://github.com/tardigrde/gcpath --- # gcpath -A CLI for querying GCP resource hierarchy paths. It translates between GCP -resource names (`folders/12345`) and human-readable paths (`//example.com/dept/team`) -and lets you explore the org → folder → project tree. +A read-only CLI for querying GCP resource hierarchy paths. Translates between +GCP resource names (`folders/12345`) and human-readable paths +(`//example.com/dept/team`) and lets you explore the org → folder → project +tree. ## When to Use **Use gcpath when asked to:** -- List what folders or projects are inside a GCP folder or organization +- List folders or projects inside a GCP folder or organization - Find the hierarchy path of a project or folder - Convert a human-readable path to a GCP resource name (for use in `gcloud`, Terraform, etc.) - Search for a project or folder by display name @@ -35,223 +45,99 @@ and lets you explore the org → folder → project tree. - Compute, GKE, Cloud Run, or other product-level resources - Resource creation or modification (gcpath is read-only) -## Installation +## Running gcpath + +Prefer the bare command if gcpath is already installed: ```bash -pip install gcpath -# or -uv add gcpath +gcpath ``` -**Authentication** — gcpath uses Application Default Credentials. Authenticate with: +If not installed, use uvx (no install required): ```bash -gcloud auth application-default login +uvx gcpath ``` -Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file. - -**Required IAM roles** (on the org or target scope): - -- `roles/resourcemanager.organizationViewer` -- `roles/resourcemanager.folderViewer` -- `roles/resourcemanager.projectViewer` -- Or: `roles/cloudasset.viewer` (Cloud Asset API mode, the default) +**Required IAM role** (on the org or target scope): `roles/cloudasset.viewer` +(default API mode), or `roles/resourcemanager.folderViewer` + +`roles/resourcemanager.projectViewer` (with `-U` flag). ## Core Concepts - **Resource names**: `organizations/123`, `folders/456`, `projects/789` or `projects/my-project-id` - **Paths**: `//example.com/Department/Team` — double-slash prefix, then org domain, then slash-separated display names - **Organizationless projects**: shown with `//_/` prefix (no org parent) -- **Entrypoint**: a default root resource to scope all commands to (set once, used implicitly) - -## Commands - -### List children: `ls` - -```bash -gcpath ls # all orgs/projects you have access to -gcpath ls folders/123 # direct children of a folder -gcpath ls folders/123 -R # all descendants, recursively -gcpath ls folders/123 -R -L 2 # recursive, max 2 levels deep -gcpath ls folders/123 -l # long format: show resource names alongside paths -gcpath ls folders/123 --type project # only projects -gcpath ls folders/123 --label env=production # filter by GCP label -gcpath ls folders/123 --tag cost-center=eng # filter by GCP tag -gcpath ls folders/123 --show-labels --show-tags # show labels/tags in output -``` - -### Tree view: `tree` - -```bash -gcpath tree # full hierarchy tree -gcpath tree folders/123 # subtree from a folder -gcpath tree folders/123 -L 3 # limit depth -gcpath tree folders/123 -i # show resource names alongside display names -gcpath tree folders/123 --type project # only show projects -gcpath tree -y # skip confirmation for large loads -``` - -### Diagram: `diagram` - -```bash -gcpath diagram # Mermaid diagram of full hierarchy -gcpath diagram folders/123 # diagram of a subtree -gcpath diagram -f d2 # D2 format instead of Mermaid -gcpath diagram -o hierarchy.mmd # write to file -gcpath diagram folders/123 -L 2 # limit depth -``` - -### Statistics: `stats` - -```bash -gcpath stats # count orgs, folders, projects globally -gcpath stats folders/123 # count within a folder subtree -gcpath stats organizations/456 -``` - -### Resolve path → resource name: `name` - -```bash -gcpath name //example.com/Department/Team -gcpath name //example.com/Department/Team --id # print only the numeric ID -gcpath name //example.com/Dept/A //example.com/Dept/B # multiple paths -``` - -### Resolve resource name → path: `path` - -```bash -gcpath path folders/123 -gcpath path projects/my-project -gcpath path folders/123 folders/456 # multiple resources -``` - -### Search by display name: `find` - -```bash -gcpath find "data-*" # glob pattern, case-insensitive -gcpath find "*team*" folders/123 # scoped to a subtree -gcpath find "prod-*" --type project -gcpath find "*" --label env=production # find all labeled resources -``` - -### Ancestry chain: `ancestors` - -```bash -gcpath ancestors projects/my-project -gcpath ancestors folders/123 -``` - -### Cache management - -```bash -gcpath cache status # show cache age, size, scope -gcpath cache clear # force next run to re-fetch from GCP -``` - -### Configuration - -```bash -gcpath config set-entrypoint folders/123 # always scope to this folder by default -gcpath config show # display current config -gcpath config clear-entrypoint -``` - -## Global Flags - -These apply to any command: - -| Flag | Short | Description | -|------|-------|-------------| -| `--entrypoint RESOURCE` | `-e` | Default scope for this invocation | -| `--json` | | Output as JSON | -| `--yaml` | | Output as YAML | -| `--force-refresh` | `-F` | Bypass cache, re-fetch from GCP API | -| `--no-use-asset-api` | `-U` | Use Resource Manager API instead of Cloud Asset API | -| `--debug` | | Enable debug logging | +- **Entrypoint**: a persistent default root resource (`gcpath config set-entrypoint folders/123`) ## Common Workflows -### 1. Find which folder a project lives in +### Find which folder/org a project belongs to ```bash -gcpath ancestors projects/my-project -# or gcpath path projects/my-project +gcpath ancestors projects/my-project # full chain with display names ``` -### 2. List all projects in a folder +### List all projects in a folder ```bash gcpath ls folders/123 -R --type project ``` -### 3. Get the resource name for a path (e.g. to use in gcloud) +### Convert a path to a resource name (e.g. for gcloud/Terraform) ```bash gcpath name //example.com/Engineering/Backend # → folders/456789 -gcloud projects list --filter="parent.id=456789" ``` -### 4. Search for a project by display name +### Search by display name ```bash gcpath find "*payments*" --type project +gcpath find "prod-*" folders/123 # scoped to a subtree ``` -### 5. Explore a subtree visually +### Explore a subtree ```bash -gcpath tree folders/123 -L 3 -i +gcpath tree folders/123 -L 3 -i # tree, depth 3, show resource IDs +gcpath ls folders/123 -R -L 2 # flat list, depth 2 ``` -### 6. Generate a diagram for docs +### Machine-readable output ```bash -gcpath diagram folders/123 -f mermaid -o team-hierarchy.mmd +gcpath --json ls -R | jq '.[] | .path' +gcpath --yaml ancestors projects/my-project ``` -### 7. Filter resources by label +### Filter by GCP labels or tags ```bash -gcpath ls --label env=production --label team=platform -R +gcpath ls -R --label env=production --label team=platform +gcpath find "*" --tag cost-center=eng ``` -## Output Formats - -By default, output is formatted for terminal readability (using Rich). For -programmatic use: - -```bash -gcpath ls folders/123 --json | jq '.[] | .path' -gcpath tree folders/123 --yaml -gcpath ancestors projects/my-project --json -``` +## Key Flags (most commands) -## API Modes - -| Mode | Flag | Speed | Permissions needed | -|------|------|-------|--------------------| -| Cloud Asset API | (default) | Fast — bulk SQL queries | `roles/cloudasset.viewer` | -| Resource Manager | `-U` | Slower — iterative paging | `roles/resourcemanager.*Viewer` | - -Use `-U` if the Cloud Asset API is not enabled in the project or if you lack the Asset Viewer role. - -## Caching +| Flag | Short | Description | +|------|-------|-------------| +| `--json` / `--yaml` | | Structured output (global) | +| `--force-refresh` | `-F` | Bypass cache, re-fetch from GCP | +| `--recursive` | `-R` | List all descendants (`ls` only) | +| `--level N` | `-L` | Max depth | +| `--type TYPE` | `-t` | Filter: `folder`, `project`, `organization` | +| `--no-use-asset-api` | `-U` | Use Resource Manager API instead | -gcpath caches hierarchy data locally to avoid repeated API calls. The cache is -scoped to the resource used. Use `-F` / `--force-refresh` to bypass it, or -`gcpath cache clear` to wipe it. +For the full flag reference, read [`references/commands.md`](references/commands.md). ## Gotchas -- `tree`, `diagram`, `stats` do not support starting from a project (projects are leaf nodes). +- `tree`, `diagram`, `stats` do not accept projects as starting point (leaf nodes). - Organizationless projects appear under `//_/` in paths. -- `--label` and `--tag` filters are ANDed together when repeated. -- `gcpath path` resolves without loading the full hierarchy (it uses the GCP ancestry API directly) — it's fast even without cache. -- Scoped loads (`gcpath ls folders/123`) are faster and not cached by default unless `folders/123` is also the configured entrypoint. - -## Reference - -See [`references/commands.md`](references/commands.md) for a compact flag reference per command. +- `--label` / `--tag` filters are ANDed when repeated. +- `gcpath path` and `gcpath ancestors` hit the GCP API directly — no cache needed, always fast. +- Scoped loads (`gcpath ls folders/123`) are not cached unless that folder is the configured entrypoint. +- Use `-U` if you get "Cloud Asset API not enabled" errors.