envctl

• npm @agilecustoms/envctl
• npm agilecustoms/packages (admin view)

usage

terraform init -backend-config=key=laxa1986
envctl deploy -var-file=versions.tfvars -var="log_level=debug"
envctl delete

setup/update

npm install -g @agilecustoms/envctl # same command for update
envctl --version
npm outdated -g
npm view @agilecustoms/envctl version # show latest version available (without installing)

npmjs setup

1. Login in npmjs.com
2. Create organization "agilecustoms" this will create scope @agilecustoms (one org => exactly one scope, also scope can be created w/o org)
3. How to add a package first time?
4. Configure Trusted publishing for npm packages
   1. Navigate to package settings
   2. Pick GitHub Actions
      1. Organization or user: agilecustoms
      2. Repository: envctl
      3. Workflow filename: build.yml
      4. Environment name: release
      5. "Set up connection"
5. In GH workflow job use permissions: id-token: write and release action with input npm-publish: true

History/motivation

env-api is a microservice hosted in 'maintenance' account and working as garbage collector: every environment first created in env-api and then 'managed' by env-api: it deletes env when it is not in use anymore OR can extend lifetime. Creation API yields unique ID, so you can safely extend lifetime via this ID

Authorization

There are two main use cases:

1. create an environment from CI (mainly ephemeral envs)
2. create env from a dev machine

Originally I (Alex C) have chosen IAM authorization (/ci/deployer on pipeline via OIDC, /developer on dev machine via SSO) Then (Feb 2026) I reworked it to use API keys

Distribution

Originally I planned to use bash scripts, but it quickly became bulky and hard to maintain. Then I thought about Node.js - it is available on dev machines and in GitHub actions (namely in Ubuntu runners). How to distribute it? First I thought about using ncc to bundle in one big .js file (as I do for publish-s3 and gha-healthcheck) but it will be hard to use on dev machine...

So I ended up publishing this client as an npm package in npmjs

• CI environments can install it via GH action agilecustoms/envctl
• developer will install it globally via npm install -g @agilecustoms/envctl

terraform init

Terraform init first time (given state configured to be in S3)

1. backend state metadata
   1. terraform checks access to remote state (double-checked, tried to specify the wrong bucket, and it fails)
      • basically it tries s3:ListObjectsV2. But it looks like it does not check access to the file itself
   2. create file .terraform/terraform.tfstate with backend config (s3 bucket and key) (it does NOT download a state file itself!)
   3. so basically if you call terraform init two times with different keys, second time you get error "Backend configuration changed" and ask to migrate state or reconfigure
2. modules (can be called individually via terraform get -update)
   1. download modules, put them in .terraform/modules
   2. modules are loaded before providers bcz in modules can be more providers!
3. providers
   1. search for the latest provider satisfying conditions in .tf files
   2. download providers, put them in .terraform/providers/*
   3. create file .terraform.lock.hcl with provider versions and hashes