gcpath 0.6.0

A CLI and Python library for querying 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

Python API

In addition to the CLI, gcpath can be used as a Python library. All core classes and functions are importable directly from the gcpath package.

Installation

pip install gcpath
# or
uv add gcpath

Basic Usage

from gcpath import Hierarchy

# Load the full GCP resource hierarchy
# The faster Cloud Asset API is recommended (requires `cloudasset.googleapis.com` enabled).
hierarchy = Hierarchy.load(via_resource_manager=False)

# Alternatively, use the default Resource Manager API. It's slower but has simpler permissions.
# hierarchy = Hierarchy.load()

# Iterate over organizations, folders, and projects
for org_node in hierarchy.organizations:
    print(org_node.organization.display_name)  # e.g. "example.com"

for folder in hierarchy.folders:
    print(folder.path)  # e.g. "//example.com/engineering/backend"

for project in hierarchy.projects:
    print(project.path, project.project_id)  # e.g. "//example.com/my-project", "my-project"

Path ↔ Resource Name Conversion

from gcpath import Hierarchy

hierarchy = Hierarchy.load(via_resource_manager=False)

# Path → resource name
resource_name = hierarchy.get_resource_name("//example.com/engineering/backend")
print(resource_name)  # e.g. "folders/123456789"

# Resource name → path
path = hierarchy.get_path_by_resource_name("folders/123456789")
print(path)  # e.g. "//example.com/engineering/backend"

# Works for organizations and projects too
org_path = hierarchy.get_path_by_resource_name("organizations/111111111")
project_path = hierarchy.get_path_by_resource_name("projects/my-project-id")

Lightweight Single-Resource Lookup

When you only need the path for one resource, resolve_ancestry() traverses up the hierarchy via individual API calls — no full hierarchy load required:

from gcpath import Hierarchy

path = Hierarchy.resolve_ancestry("folders/123456789")
print(path)  # e.g. "//example.com/engineering/backend"

Scoped Loading

For large hierarchies or restricted access, scope the load to a specific folder or organization:

from gcpath import Hierarchy

# Load only the subtree under a specific folder (recursive)
hierarchy = Hierarchy.load(
    via_resource_manager=False,
    scope_resource="folders/123456789",
    recursive=True,
)

# Load only direct children of a folder
hierarchy = Hierarchy.load(
    via_resource_manager=False,
    scope_resource="folders/123456789",
    recursive=False,
)

Error Handling

from gcpath import Hierarchy, GCPathError, ResourceNotFoundError, PathParsingError

try:
    hierarchy = Hierarchy.load(via_resource_manager=False)
    name = hierarchy.get_resource_name("//example.com/nonexistent/path")
except ResourceNotFoundError as e:
    print(f"Resource not found: {e}")
except PathParsingError as e:
    print(f"Invalid path format: {e}")
except GCPathError as e:
    print(f"gcpath error: {e}")

API Reference

Symbol	Description
Hierarchy	Main class. Load with Hierarchy.load(), then query with get_resource_name(), get_path_by_resource_name().
Hierarchy.load()	Load the full hierarchy from GCP. Key params: via_resource_manager, scope_resource, recursive.
Hierarchy.resolve_ancestry()	Lightweight static method to resolve a single resource name to path.
OrganizationNode	Represents a GCP organization with its folders.
Folder	Represents a GCP folder. Has .path, .name, and .display_name attributes.
Project	Represents a GCP project. Has .path, .project_id, .name, and .display_name attributes.
GCPathError	Base exception class for all gcpath errors.
ResourceNotFoundError	Raised when a resource cannot be found in the hierarchy.
PathParsingError	Raised when a path string cannot be parsed.
path_escape()	URL-encodes a display name for safe use in paths.

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