gcloud2-wrap 1.0.0
A wrapper for executing commands with Google Cloud CLI authentication and project management
License: MIT
Requires Python: >=3.9
Keywords: gcloud, google, cloud, project, authentication, wrapper


# gcloud2-wrap

A Python wrapper for executing commands with Google Cloud CLI authentication and project management.

## Overview

`gcloud2-wrap` is a Python tool that provides enhanced functionality for running commands with Google Cloud Platform (GCP) authentication and project context. It's designed as a more robust and feature-rich replacement for bash-based wrappers.

## Features

- **Automatic Project Management**: Seamlessly switch between GCP projects for command execution
- **Quota Project Handling**: Automatically sets quota project if not specified
- **Authentication Recovery**: Detects authentication errors and automatically triggers `gcloud auth application-default login`
- **State Restoration**: Automatically restores original gcloud configuration after command execution
- **Signal Handling**: Properly forwards signals (SIGINT, SIGTERM) to child processes
- **Environment Variable Management**: Sets appropriate Google Cloud environment variables
- **Error Handling**: Comprehensive error handling with meaningful error messages

## Installation

### From PyPI (recommended)

```bash
pip install gcloud2-wrap
```

### From Source

```bash
git clone https://github.com/ravishtiwari/gcloud2-wrap.git
cd gcloud2-wrap
pip install -e .
```

## Usage

### Basic Usage

```bash
gcloud2-wrap --project PROJECT_ID --credentials /path/to/credentials.json -- COMMAND [ARGS...]
```

### With Quota Project

```bash
gcloud2-wrap --project PROJECT_ID --quota-project QUOTA_PROJECT_ID --credentials /path/to/credentials.json -- COMMAND [ARGS...]
```

### Examples

Run a gcloud command with specific project context:

```bash
gcloud2-wrap --project my-project --credentials ./service-account.json -- gcloud compute instances list
```

Run a Python script with GCP authentication:

```bash
gcloud2-wrap --project my-project --credentials ./service-account.json -- python my_gcp_script.py
```

Run with different quota project:

```bash
gcloud2-wrap --project my-project --quota-project billing-project --credentials ./service-account.json -- gcloud storage ls
```

## Command Line Options

- `--project PROJECT_ID`: **(Required)** GCP project ID to use for the command
- `--credentials PATH`: **(Required)** Path to the service account credentials JSON file
- `--quota-project PROJECT_ID`: *(Optional)* GCP quota project ID (defaults to the value of `--project`)
- `--version, -v`: Show version information
- `--`: Separator between wrapper options and the command to execute

## Environment Variables

The tool automatically sets the following environment variables for the executed command:

- `GOOGLE_APPLICATION_CREDENTIALS`: Path to the credentials file
- `GOOGLE_CLOUD_PROJECT`: The specified project ID
- `GOOGLE_CLOUD_QUOTA_PROJECT`: The specified quota project ID

## Enhanced Features

### Automatic Quota Project

If `--quota-project` is not specified, the tool automatically uses the same value as `--project`.

### Authentication Error Recovery

When the tool detects authentication-related errors in command output, it automatically runs:

```bash
gcloud auth application-default login
```

This helps recover from expired or invalid authentication tokens.

### State Restoration

The tool saves the current gcloud configuration before making changes and restores it after command execution, ensuring your local gcloud setup remains unchanged.

### Signal Handling

Proper signal forwarding ensures that interrupting the wrapper (Ctrl+C) correctly terminates the child process.

## Development

For information on setting up the development environment, running tests, and the CI/CD pipeline, please refer to [DEVELOPMENT.md](DEVELOPMENT.md).

## Requirements

- Python 3.9 or higher
- Google Cloud CLI (`gcloud`) installed and available in PATH
- `psutil` package (automatically installed with the package)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

If you encounter any issues or have questions, please file an issue on the [GitHub repository](https://github.com/ravishtiwari/gcloud2-wrap/issues).