cloudpin

cloudpin

Pin cloud accounts to a project, and stop any command (yours or your AI agent's) that would run on the wrong one.

az, aws, gcloud, vercel, gh, kubectl, helm, supabase and wrangler act on whichever account, cluster or project you used last. With a work account, a personal one and a client or two on the same machine, sooner or later something gets deployed to, or deleted from, the wrong place. Coding agents make it more likely: they run these commands for you and never stop to ask which account is active. cloudpin checks before the command runs.

Install

pnpm add --global cloudpin

On macOS and Linux, Homebrew works too, from paureis/homebrew-tap (it runs on Homebrew's own Node.js, installed if it isn't there yet):

brew install paureis/tap/cloudpin

On Windows, Scoop works too, from paureis/scoop-bucket. It installs Scoop's own Node.js (nodejs-lts) if needed, and cloudpin always runs on that one. A global install (scoop install -g) needs nodejs-lts installed globally too. nodejs-lts puts its folders at the front of your user PATH, so in new shells node and npm are Scoop's (and npm install --global installs there), ahead of any other Node.js on your user PATH; one on the system PATH, where the nodejs.org installer puts it, still comes first. Uninstalling nodejs-lts breaks cloudpin until you run scoop install nodejs-lts again, and Scoop's no_junction setting isn't supported.

scoop bucket add paureis https://github.com/paureis/scoop-bucket

scoop install paureis/cloudpin

Without Node.js at all, each release from 1.3.0 has a standalone cloudpin.exe for 64-bit Windows: unzip cloudpin-X.Y.Z-win-x64.zip from Releases into a folder on your PATH. It carries its own Node.js, so a Node.js security fix reaches it only in a new cloudpin. winget (winget install paureis.cloudpin) comes with 1.3.0 too.

npm, Yarn, Bun, or no install

npm install --global cloudpin

yarn global add cloudpin bun add --global cloudpin

try it without installing

npx cloudpin --help

Requires Node.js 22 or later. Works on Windows, macOS and Linux. The .cloudpin.yml format is stable from 1.0 on (see Configuration), and feedback is very welcome.

Latest release: 1.2.3 (2026-11-05): two security fixes since 1.2.1, please upgrade. 1.2.1 (2026-10-29): agent hooks now find calls hidden by heredocs in $( ), run-time values, PowerShell syntax and wrappers such as xargs, sudo, npx or cmd /c, and gcloud checks the impersonated account; please upgrade. 1.2.0 (2026-10-29) was run it everywhere. A GitHub Action (paureis/cloudpin-action) checks the accounts before a deploy job, built on the new cloudpin check --only and --json; Homebrew and Scoop installs; the MCP server for every agent, listed in the official MCP Registry (docs/mcp.md); Codex and Copilot CLI hooks that PowerShell's execution policy can't stop on Windows; and fixes to which Vercel team and Wrangler account a command uses. See the CHANGELOG. 1.1 added the Claude Code plugin, and 1.0 made the .cloudpin.yml format stable.

Quick start

cd your-project

cloudpin init # pin the accounts you are logged into now cloudpin install-hook claude # protect your AI agent (or codex, cursor, copilot, antigravity, gemini) echo 'eval "$(cloudpin shell-init bash)"' >> ~/.bashrc # protect your terminal

Commit .cloudpin.yml so everyone on the project gets the same protection. cloudpin status shows each CLI's active account next to what is pinned. To see a block without risking anything, pin a wrong account in a scratch folder (edit an ID in .cloudpin.yml) and run a read-only command such as gh repo list.

To undo it all: cloudpin uninstall-hook claude, remove the shell-init line from your profile, and delete .cloudpin.yml. The only other things cloudpin writes are a short-lived identity cache in your user cache folder, .git/cloudpin-env if you ran cloudpin use, and *.cloudpin-backup copies next to agent settings it edited.

Usage

# Write .cloudpin.yml from the accounts you are logged into now

cloudpin init

...or add them as one environment of the file (see Environments)

cloudpin init --env production --protected

Show the environments, or choose the one to use in this clone

cloudpin use [ | --clear]

Check every pinned account; exit 1 on a mismatch (handy in CI and scripts)

cloudpin check

Check only these clouds; each must be pinned, installed and logged in to the pinned

account, so a CLI missing on the runner fails, not skipped. --json prints an overall "result" (match,

mismatch, unpinned or error) and each cloud's status, reason and fix. Exit codes stay the same.

cloudpin check --only azure,aws [--json]

Switch each pinned CLI to its pinned account: shows the plan, asks once (--yes: don't ask), runs the CLIs' own switch

commands, then checks again; exit 1 unless everything matches. What it won't do (a login, supabase link, a Wrangler

config edit, an overriding variable) it names for you. --json: the plan, what ran and the check after.

cloudpin switch [--yes] [--json] [--only ]

See each CLI's active account, what this folder pins, and which agent hooks are installed (--json for tools)

cloudpin status

Why was a command blocked, or would it be? See the pin, the account it would use, and the verdict, without

running it. One quoted argument is read as a full line; --agent shows what an agent hook decides; --json for tools.

cloudpin explain -- vercel deploy --prod cloudpin explain "cd ../web && vercel deploy"

Something looks off? Check the whole setup and get the fix for each problem; exit 1 if anything fails.

--json shortens account IDs and hides your home folder, so it is safe to paste in a bug report.

cloudpin doctor [--json]

Run one command only if it would act on the pinned account; exit 3 if blocked

cloudpin exec -- vercel deploy --prod

Shell functions that route az, aws, gcloud, vercel, gh, kubectl, helm, supabase and wrangler through cloudpin

cloudpin shell-init bash|zsh|pwsh

Add or remove the hook in an agent's settings (this project, or yours with --user)

cloudpin install-hook [--user] cloudpin uninstall-hook [--user]

How it works

A .cloudpin.yml in your project lists the accounts it uses. cloudpin init writes it for you, with readable names as comments:

azure:

subscription: "3f2a0000-0000-0000-0000-000000000c91" # Acme Prod tenant: "8b1d0000-0000-0000-0000-00000000044e" aws: account: "123456789012" gcloud: account: "deploy@acme.com" project: "acme-prod" vercel: team: "team_x9KqZr" # acme github: user: "acme-bot" kubernetes: server: "https://acme-prod.hcp.westeurope.azmk8s.io:443" # acme-prod-admin namespace: "payments" supabase: project: "abcdefghijklmnopqrst" # Acme prod org: "acme" cloudflare: account: "0123456789abcdef0123456789abcdef" # Acme

Before a guarded command runs, cloudpin works out which account that command would use (asking the CLI, or for Kubernetes reading the kubeconfig), honouring the command's own flags and environment, and compares the answer with the file:

For Kubernetes the server URL is pinned rather than the context name, because context names are personal: the same cluster is prod on one laptop and acme-prod-admin on another. init writes your context name as a comment, and pins the namespace only if your context sets one. With a namespace pinned, -A / --all-namespaces is a mismatch. Commands that never reach a cluster (kubectl config, kubectl kustomize, helm template, helm repo, ...) are never blocked, and standalone kustomize isn't guarded at all. cloudpin can't see a namespace: written inside a manifest you apply, so pin the namespace and keep manifests namespace-free if that matters to you.

For gcloud, an impersonated service account (the last one in a delegation chain) is the account compared with the pin; with an access token or token file the account can't be known, so an account pin gives "can't tell".

For Supabase the project ref is worked out the way the CLI does it, without a network call: --project-ref, then SUPABASE_PROJECT_ID, then the project supabase link saved in supabase/.temp/. A linked branch counts as its parent project. The organisation comes from supabase projects list. The local stack (start, stop, status, functions serve, and db reset, db diff or migration up without --linked) is never blocked. A --db-url pointing anywhere but your own machine is stopped, because cloudpin can't tell which project a URL belongs to.

For Cloudflare, cloudpin follows Wrangler's order: account_id in the config file Wrangler would find, then CLOUDFLARE_ACCOUNT_ID, then the account Wrangler cached, then the only account the login sees (wrangler whoami --json), with the auth profile the command uses (--profile or wrangler auth activate). Variables Wrangler loads from the project's .env files count too. If it sees several and none is set, Wrangler would ask or fail, so cloudpin stops the command, as for a profile it can't ask about. Local commands (dev, and d1, kv key or r2 object without --remote) are never blocked; dev with remote: true bindings reaches your account unchecked. Built to Wrangler's source and docs,