@zerocarbon/deploy

Local production deploy CLI for ZeroCarbon AWS services when GitHub Actions minutes are unavailable.

Run it from inside a ZeroCarbon repo:

npx @zerocarbon/deploy

The CLI detects the current Git repository, maps it to the production AWS service, creates an isolated temporary clone, refreshes the default branch there from origin, builds and pushes the Docker image from that clean source, deploys ECS or Lambda, verifies the public endpoint, and cleans Docker artifacts from the run.

Commands

npx @zerocarbon/deploy              # deploy current repo
npx @zerocarbon/deploy doctor       # check local tools and AWS target
npx @zerocarbon/deploy list         # show supported services
npx @zerocarbon/deploy --dry-run    # print deploy plan only

Non-Negotiable Source Rule

Deploys always use the origin default branch. The user cannot override the branch.

The CLI checks:

git ls-remote --symref origin HEAD
git clone --no-checkout --branch <defaultBranch> <localRepo> <tempControlClone>
git fetch --prune origin <defaultBranch>
git branch -D <defaultBranch>              # inside tempControlClone only
git branch <defaultBranch> origin/<defaultBranch>
git worktree add <tempWorktree> <defaultBranch>

The local checkout is only used to identify the repo and seed the temporary clone. Local files, local commits, dirty changes, and the current local branch are ignored for deployment. The SDK deletes the temporary worktree and the temporary control clone after doctor, dry-run, success, or failure.

Required Local Tools

• Node.js 20+
• Docker Desktop or OrbStack with Docker CLI
• AWS CLI v2 authenticated to production account
• Git
• npm/pnpm/yarn as required by the target repo

doctor can install and start the deploy dependencies on macOS and Windows:

npx @zerocarbon/deploy doctor

If Docker is missing, it asks before installing:

• macOS: installs Homebrew if needed, then runs brew install --cask docker
• Windows: runs winget install --id Docker.DockerDesktop -e --accept-package-agreements --accept-source-agreements
• Windows without winget: downloads Docker Desktop installer and runs it quietly
• Windows without admin shell: asks for permission, opens UAC for the installer command, waits, then resumes the same CLI session

If Docker is installed but not running, it opens Docker Desktop and waits for docker version.

If AWS CLI is missing, it asks before installing:

• macOS with Homebrew: brew install awscli
• macOS without Homebrew: downloads AWSCLIV2.pkg and runs sudo installer
• Windows: winget install --id Amazon.AWSCLI -e --accept-package-agreements --accept-source-agreements
• Windows without winget: downloads AWSCLIV2.msi and runs msiexec
• Windows without admin shell: asks for permission, opens UAC for the installer command, waits, then resumes the same CLI session

If AWS CLI is installed but not logged in, it asks to run AWS login. SSO users get aws configure sso when the selected profile has no SSO config, then aws sso login. Access-key users can choose aws configure.

Supported Targets

ECS:

• ZeroCarbonBackend
• chat
• zerocarbon-agent
• ZeroCarbonWebsite
• ZerocarbonDashboard
• prod-auth
• CRM
• erp
• esg

Lambda image:

• Calculator
• cbam
• climate-api
• country
• gresb
• ncb
• pcaf
• plants
• smart-carbon
• supply-chain
• survey
• upload-report
• checkout

Unsupported repos fail clearly instead of pretending to deploy.

Cleanup

By default the CLI removes the temporary source worktree, removes images created by this run, and prunes Docker build cache.

For aggressive cleanup:

npx @zerocarbon/deploy --full-prune

It requires typing PRUNE EVERYTHING because it deletes unused Docker volumes.