CloudSQLCTL

cloudsqlctl is a Windows-native command-line tool designed to simplify the management of the Google Cloud SQL Auth Proxy. It integrates seamlessly with the gcloud CLI to provide a robust, production-ready experience for developers working on Windows.

Features

• Setup Wizard: Interactive setup command to get everything running in minutes.
• Authentication Management: Built-in auth command for gcloud login, ADC setup, and Service Account management.
• Automated Installation: Downloads and verifies the official Cloud SQL Proxy binary.
• Instance Management: Lists and selects Cloud SQL instances using your active gcloud configuration.
• Process Management: Starts, stops, and restarts the proxy as a background process or Windows Service.
• Structured Logging: JSON logging with automatic masking of sensitive tokens.
• Diagnostics: Built-in doctor command to check environment health (gcloud, ADC, network, service).
• Self-Update: Easily update the proxy binary to the latest version.

Installation

Primary distribution is via GitHub Releases:

• Download the latest installer (cloudsqlctl-setup.exe) from the Releases page.

Optional/community distribution:

• Scoop: see scoop/README.md
• Winget/Chocolatey: see docs/Distribution.md

Documentation

Full documentation is available in the docs folder:

• Wiki Home
• Installation Guide
  • Configuration & Setup
  • Command Reference
  • Distribution
  • Enterprise Policy
  • Troubleshooting

Quick Start

Run the setup wizard to configure gcloud, authentication, and the proxy:

cloudsqlctl setup

Usage

cloudsqlctl [command] [options]

For a complete reference of all commands and options, see the Command Reference.

Commands

Command	Description
setup	Interactive setup wizard (Recommended for first run).
auth	Manage authentication (Login, ADC, Service Accounts).
install	Download and install the Cloud SQL Proxy binary.
update	Update the Cloud SQL Proxy binary to the latest version.
upgrade	Upgrade cloudsqlctl to the latest version.
list	List available Cloud SQL instances.
select	Interactively select a Cloud SQL instance to proxy.
connect	Connect to a specific instance directly.
start	Start the proxy for the selected instance.
stop	Stop the running proxy process.
service	Manage Windows Service (Admin required).
env	Manage environment variables (User/Machine scope).
gcloud	Manage Google Cloud CLI (install portable version).
status	Check if the proxy is running and view details.
paths	Show resolved paths and configuration locations.
logs	View the tail of the proxy logs.
doctor	Run diagnostics to verify environment setup.
check	Verify full system configuration.
repair	Self-heal missing or corrupted files/config.
ps1	Manage PowerShell scripts.
support	Create a support bundle zip for troubleshooting.
reset	Reset configuration and remove local files.

Authentication Modes

1. Developer Mode (Interactive) Uses your personal Google Cloud credentials via gcloud.

cloudsqlctl auth login
cloudsqlctl auth adc

2. Machine/Service Mode (Service Account) Uses a Service Account JSON key. Ideal for automated environments or Windows Services.

# Securely install service account key (Machine scope requires Admin)
cloudsqlctl auth set-service-account --file "C:\path\to\key.json" --scope Machine

Windows Service

Run the proxy as a Windows Service for background persistence.

# Install service (Admin required)
cloudsqlctl service install --instance "my-project:region:instance" --port 5432

# Configure startup type (Automatic, Manual, Disabled, Delayed)
cloudsqlctl service startup Automatic

# Start service
cloudsqlctl service start

# Check status
cloudsqlctl service status

Interactive Authentication

Manage Service Account keys interactively:

# List installed keys
cloudsqlctl auth list-keys

# Interactively select a key to use
cloudsqlctl auth select-key

Configuration

Configuration and logs are stored in:

• User Scope (Default):

  • Config: %LOCALAPPDATA%\CloudSQLCTL
  • Logs: %LOCALAPPDATA%\CloudSQLCTL\logs
  • Binary: %LOCALAPPDATA%\CloudSQLCTL\bin

• Machine Scope (Service):

  • Config: %ProgramData%\CloudSQLCTL
  • Logs: %ProgramData%\CloudSQLCTL\logs
  • Binary: %ProgramData%\CloudSQLCTL\bin

Path Resolution Logic:

1. Environment Variables (CLOUDSQLCTL_HOME, etc.)
2. Existing System Installation (%ProgramData%)
3. Existing User Installation (%LOCALAPPDATA%)
4. Default: User Scope (%LOCALAPPDATA%)

Verify current paths with:

cloudsqlctl paths

Release

This project uses GitHub Actions for automated releases.

1. Tag a new version: git tag v0.3.0
2. Push the tag: git push origin v0.3.0
3. The workflow will build, test, sign (if configured), and publish artifacts to the Releases page.
4. If a rerun is needed, use the Release workflow workflow_dispatch with the tag input.
5. NPM publish runs on release publication (requires NPM_TOKEN secret).

Troubleshooting

If you encounter issues:

1. Run cloudsqlctl doctor to check for common problems.
2. Check the logs in %LOCALAPPDATA%\CloudSQLCTL\logs.
3. Ensure gcloud is installed and authenticated (gcloud auth login).

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Development

Prerequisites

• Node.js 22 (LTS)
• PowerShell 5.1 or later

Build

To build the project and generate the single executable:

# Install dependencies
npm install

# Build the source code (TypeScript -> CJS)
npm run build

# Package into a single executable (SEA)
npm run package

The executable will be generated at bin/cloudsqlctl.exe.

License

MIT