gcpath 0.5.1

A CLI utility to manage Google Cloud Platform resource hierarchy paths.

gcpath

gcpath is a CLI utility to query Google Cloud Platform resource hierarchy paths. It helps you translate between GCP resource names (e.g., folders/12345) and human-readable paths (e.g., //example.com/department/team).

Why should I use gcpath?

• familiar linux-like CLI
• 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

Features

• Tree Visualization: View your hierarchy as a tree.
• Recursive Listing: List all folders and projects in your organization as paths.
• Path Resolution: Get the resource name (ID) for a given path.
• Reverse Lookup: Get the path for a given resource name (ID).
• Dual Mode:
  • Cloud Asset API (Default): Fast, bulk loading using GCP Cloud Asset Inventory.
  • Resource Manager API: Iterative loading using standard Resource Manager API (slower, but different permissions).

Roadmap

• caching, for lightning fast lookups
• diagram generation
• entrypoint configuration (organization or folder)
• IAM policies
• other resources

Prerequisites

Authentication

gcpath uses Google Cloud Application Default Credentials (ADC).

1. Install gcloud CLI.

2. Authenticate:

   gcloud auth application-default login
   

Permissions

Ensure you have enough permissions on your entrypoint (organization or folder), see API modes.

Quick Start

# List all resources
gcpath ls

# List children of a specific folder
gcpath ls folders/123456789

# Find ID of a specific path
gcpath name //example.com/engineering

# Find path of a specific resource ID
gcpath path folders/123456789

# View tree rooted at organization
gcpath tree

# View tree rooted at folder
gcpath tree folders/123456789

# Generate a Mermaid diagram of the hierarchy
gcpath diagram

# Generate a D2 diagram scoped to a folder
gcpath diagram folders/123456789 --format d2

Usage

List Resources (ls)

List folders and projects. Defaults to the organization root.

gcpath ls [RESOURCE_NAME]

Options:

• -l, --long: Show resource IDs and numbers (for projects).
• -R, --recursive: List resources recursively.

Examples:

# List all organizations and their top-level children
gcpath ls

# List all contents of an organization recursively
gcpath ls -R

# List children of a specific folder
gcpath ls folders/123456789

Tree View (tree)

Visualize the resource hierarchy in a tree format.

gcpath tree [RESOURCE_NAME]

Options:

• -L, --level N: Limit depth of the tree (no limit by default).
• -i, --ids: Include resource IDs in the output.
• -y, --yes: Skip confirmation prompts for large hierarchy loads.

Generate Diagram (diagram)

Generate a Mermaid or D2 diagram of the resource hierarchy.

gcpath diagram [RESOURCE_NAME]

Options:

• -f, --format FORMAT: Output format: mermaid (default) or d2.
• -L, --level N: Limit depth of the diagram.
• -i, --ids: Include resource IDs in node labels.
• -o, --output FILE: Write diagram to a file instead of stdout.
• -y, --yes: Skip confirmation prompts for large hierarchy loads.

Examples:

# Generate Mermaid diagram of the full hierarchy
gcpath diagram

# Generate D2 diagram scoped to a folder
gcpath diagram folders/123456789 --format d2

# Save Mermaid diagram to a file with depth limit
gcpath diagram -L 3 -o hierarchy.mmd

# Include resource IDs in labels
gcpath diagram --ids

Get Resource Name (name)

Get the GCP resource name (e.g., folders/123) from a path:

gcpath name //example.com/engineering/backend

To get just the ID:

gcpath name --id //example.com/engineering/backend

Get Path (path)

Get the path from a resource name:

gcpath path folders/987654321

API Modes

gcpath supports two GCP APIs for loading resource hierarchy data:

Cloud Asset API (Default - Recommended)

Fast bulk loading via Cloud Asset Inventory. Recommended for most users.

# Use Cloud Asset API (default)
gcpath ls
gcpath ls --use-asset-api  # explicit
gcpath ls -u               # short form

Advantages:

• 5-6x faster than Resource Manager API
• Supports scoped loading (ls folders/123, tree folders/123)
• Efficient for large hierarchies (1000+ folders)

Required Permissions:

• cloudasset.assets.searchAllResources
• resourcemanager.organizations.get
• resourcemanager.folders.get
• resourcemanager.projects.get

Setup: Requires Cloud Asset API to be enabled: gcloud services enable cloudasset.googleapis.com

Resource Manager API

Traditional recursive API calls. Use when Cloud Asset API is not available.

# Use Resource Manager API
gcpath ls --no-use-asset-api
gcpath ls -U  # short form

Advantages:

• Works without Cloud Asset API enabled
• Simpler permission model
• Standard resourcemanager.* permissions

Required Permissions:

• resourcemanager.organizations.get
• resourcemanager.folders.list
• resourcemanager.projects.list
• resourcemanager.projects.get

Which Should I Use?

• For most users: Use the default (Cloud Asset API) for best performance
• If you get permission/API errors: Use -U flag for Resource Manager API

Entrypoint Configuration

If you're a folder admin without organization-level access, or simply want to focus on a specific part of the hierarchy, you can configure an entrypoint. This scopes all commands to a subtree, improving performance and relevance.

Setting an Entrypoint

# Set a default entrypoint (persisted in ~/.gcpath/config.json)
gcpath config set-entrypoint folders/123456789

# Show current configuration
gcpath config show

# Remove the entrypoint
gcpath config clear-entrypoint

One-off Override

Use the --entrypoint / -e flag to override the configured entrypoint for a single command:

gcpath -e folders/987654321 ls
gcpath -e folders/987654321 tree

Behavior

• When an entrypoint is set, commands like ls, tree, diagram, and name automatically scope to that resource.

• Passing an explicit resource argument overrides the entrypoint:

  gcpath ls folders/555  # uses folders/555, not the configured entrypoint
  

• The cache is scope-aware: cached data stores which entrypoint it was built for. Changing the entrypoint automatically invalidates the cache and triggers a fresh load.

Acknowledgments

Thanks for xebia/gcp-path for the inspiration!

License

MIT