RUST CLI · NO GCLOUD SDK · MIT LICENSE

Google Cloud Shell from your terminal.

I built gcs because I wanted to SSH into Cloud Shell without installing the whole gcloud SDK. It is a single Rust binary that signs in like gcloud, wakes suspended environments, and pipes ssh, scp, and editor connections over Google’s WebSocket tunnel.

Single Rust binary No SSH keys to manage Port forwards & SOCKS5 Shared gcloud ADC Agent skill included
QUICK INSTALL Requires OpenSSH on PATH
brew install aeroxy/tap/gcs

001 What it gives you
gcs ssh 01

Full SSH passthrough & SOCKS5

Open an interactive shell or run a remote command like gcs ssh uptime. Every SSH option passes through unchanged, so port forwards (-N -L 8080:localhost:8080), backgrounding (-f), and a SOCKS5 proxy out through Cloud Shell (-N -D 7890) work as usual.

gcs scp 02

Two-way file copy with cs:

Copy files and directories in either direction with your system scp. Prefix Cloud Shell paths with cs: — for example gcs scp -r ./site cs:~/site to upload or gcs scp cs:~/out.log . to pull logs locally.

wss://...2222 03

No SSH keys to manage

gcs connects over the same WebSocket tunnel gcloud uses on port 2222, where Cloud Shell accepts tunnelled sessions without an SSH key. Need port 22? Pass --port 22.

gcs start 04

Auto-wakes sleeping shells

If your Cloud Shell environment is suspended, start, ssh, scp, and ssh-proxy wake it up and wait until it is running (around half a minute) before opening the tunnel.

gcs auth login 05

Browser login & shared ADC

Signs in with your browser (or --no-browser over headless SSH) and writes gcloud’s Application Default Credentials file, so gcloud, Google’s client libraries, and Terraform can use it too — or pass an access token via flag, file, or env var.

skills/gcs 06

Built-in coding agent skill

Ships with skills/gcs/SKILL.md so Claude Code, opencode, and other coding agents know how to run commands in Cloud Shell, when to ask you to sign in, and what to do about each error.

002 Workflows & commands

Shells, port forwards, and SOCKS5 egress

Place gcs options (--credentials, --port, --authorize-session) before the SSH arguments. Everything after is passed directly to ssh.

  • -L reaches a fixed port inside Cloud Shell.
  • -D opens a local SOCKS5 proxy that routes traffic and DNS (socks5h://) out through Cloud Shell.
  • Add -N for no remote shell, and -f to background once connected.
gcs ssh                                                  # interactive shell
gcs ssh uptime                                           # run one command
gcs ssh -N -L 8080:localhost:8080                        # forward port 8080
gcs ssh -N -D 7890                                       # SOCKS5 on 127.0.0.1:7890
curl -x socks5h://127.0.0.1:7890 https://www.google.com  # DNS resolved in Cloud Shell
Command What it does
gcs auth login [--no-browser] Sign in with a browser and write gcloud’s ADC file. --no-browser prints a link and prompts for the code (auto-picked on headless Linux).
gcs auth logout Revoke the ADC file’s credentials and delete the file. Refuses raw access tokens to protect upstream refresh tokens.
gcs auth status Show which credentials are in use, account, expiry, and scopes. Exits 1 if they will not work.
gcs auth token Print an access token to stdout.
gcs info [--json] Show the Cloud Shell environment: state, username, host, and image.
gcs start Start Cloud Shell and wait until it is running.
gcs ssh [--authorize-session] [--port N] [SSH_ARGS...] Connect with ssh. Arguments go through unchanged: options first, then an optional remote command.
gcs scp [--port N] [SCP_ARGS...] Copy with scp. Prefix Cloud Shell paths with cs:, e.g. gcs scp cs:~/out.log .
gcs ssh-proxy [--port N] Pipe stdin/stdout to Cloud Shell’s sshd over the WebSocket tunnel, for SSH’s ProxyCommand.
003 Editors & coding agents
VS CODE REMOTE-SSH · ZED · OPENSSH gcs ssh-proxy

Open Cloud Shell like any other host

Add a host block to ~/.ssh/config using the username from gcs info. Then connect to cloudshell in VS Code Remote-SSH, Zed, or plain ssh cloudshell. Cloud Shell generates a fresh host key on each start, which the two host-key lines handle cleanly.

Host cloudshell
    User YOUR_CLOUD_SHELL_USERNAME
    ProxyCommand gcs ssh-proxy
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
CLAUDE CODE · OPENCODE · AGENTS skills/gcs/SKILL.md

Agent skill included in the repo

Link the bundled skills/gcs directory into your agent’s skills folder. It teaches coding agents how to run commands safely in Cloud Shell, to pause and ask you to run gcs auth login when needed, and how to handle every error code.

ln -s "$PWD/skills/gcs" ~/.claude/skills/gcs
Agent-safe defaults: teaches agents to check gcs auth status first, ask before opening a browser login, and avoid leaking --access-token in process args.
004 Credentials & how it works
CREDENTIAL PRECEDENCE (FIRST MATCH WINS)
  1. 01
    CLI Flags

    --access-token TOKEN, --access-token-file PATH, or --credentials PATH

  2. 02
    Environment Variables

    $GCS_ACCESS_TOKEN, then $GCS_ACCESS_TOKEN_FILE, then $GOOGLE_APPLICATION_CREDENTIALS

  3. 03
    gcloud’s Default ADC File

    ~/.config/gcloud/application_default_credentials.json (or %APPDATA%\gcloud\… / $CLOUDSDK_CONFIG)

Access tokens are used as given and never refreshed (a token file is re-read on every run). ADC files must hold a user sign-in (authorized_user); service-account keys are refused because Cloud Shell belongs to a user.

ADC COMPATIBILITY & LIMITATIONS
Shared with Google client libraries & Terraform: gcs auth login writes the same file gcloud auth login --update-adc writes, needing no quota project. Credentials from gcloud auth application-default login also work with --quota-project or $GCS_QUOTA_PROJECT.

How the tunnel works

gcs calls the Cloud Shell API to wake your environment and obtain a short-lived tunnel token, then spawns your local ssh or scp over a WebSocket tunnel to wss://<webHost>/_cloudshell/tcp/2222.

Current limitations (v0.1.0)

  • Needs OpenSSH (ssh, scp) installed on your PATH.
  • Direct connections only: HTTPS_PROXY is ignored by the WebSocket tunnel for now.
  • No key-based fallback (gcloud’s deprecated AddPublicKey path).
  • Built and tested on macOS; Linux should work; Windows is untested.
005 Install gcs
RELEASE V0.1.0 · OPEN SOURCE UNDER MIT

Ready in one command.

Install the prebuilt macOS arm64 binary via Homebrew, or compile from source anywhere with Cargo.

Homebrew · macOS arm64 Prebuilt
brew install aeroxy/tap/gcs
Cargo · Build from source Rust
cargo install --locked --git https://github.com/aeroxy/google-cloud-shell-cli --tag 0.1.0
Requires OpenSSH (ssh, scp) on your PATH.