envctl

A personal, gh-style command-line tool for managing deployment configuration and atomically rotating provider secrets across projects and their environments. The hosting/secret providers (Vercel, Firebase, …) sit behind the tool as pluggable backends.

See the Vision for the design and desired functionality.

Install

envctl is published publicly to npmjs as @rmartz/envctl and installed as a personal global CLI — never a per-project dependency. No token or .npmrc setup is needed.

Install and update:

pnpm add -g @rmartz/envctl         # install
pnpm add -g @rmartz/envctl@latest  # update to the newest release

If your ~/.npmrc maps the @rmartz scope to GitHub Packages (other @rmartz packages live there), that mapping wins and you'll only see old envctl versions. Override it for the install:

pnpm add -g @rmartz/envctl@latest --@rmartz:registry=https://registry.npmjs.org/

Then, from any project directory:

envctl --version
envctl config push --dry-run   # preview the public-var sync for the current project
envctl config pull             # write .env.local from the development environment
envctl secrets rotate          # atomically rotate Firebase/Sentry secrets and redeploy
envctl secrets init firebase   # bootstrap secrets for a fresh project (auto-detects if omitted)

secrets rotate mints each new credential, redeploys, then invalidates the old one, so the project is never left without a working credential. It relies on the same auth as the rest of the CLI — VERCEL_TOKEN or vercel login, SENTRY_AUTH_TOKEN, and an authenticated gcloud for Firebase key minting (run envctl auth status to check). Pass --no-invalidate to keep the old keys or --refresh-previews to redeploy active PR previews afterward.

New to a project, or unsure which command to reach for? Start with the Vercel deploy runbook — a scenario-driven playbook (cold-start, mint, rotate, add a provider, public-var change, local pull) with copy-pasteable sequences and a "how you know it worked" check for each. For mechanism detail, see the secrets rotation engine for the full mint → deploy → verify → invalidate flow, and the docs index for the config-push and environments subsystems.

Bootstrap a blank environment

Bring a linked but otherwise empty Vercel project fully online in one step:

envctl bootstrap

Prerequisites:

1. A linked Vercel project (.vercel/project.json, created by vercel link)
2. An authenticated gcloud with a pre-existing Firebase project and service account — if the project uses Firebase (envctl mints keys for existing resources; creating the service account from scratch is tracked in #70)
3. A Sentry token (SENTRY_AUTH_TOKEN or sentry-cli login) and a pre-existing Sentry project — if the project uses Sentry

bootstrap runs four phases in order: push public variables (config push), initialize any missing provider secrets (secrets init), pull a local dotenv file (config pull), and trigger redeployments so running environments pick up the pushed vars (triggerAndWaitRedeployments — skipped with a log message on a zero-deployment project). It is idempotent — safe to re-run after a partial failure, and existing secrets are never rotated. Pass --dry-run to preview every phase without making changes.

See the Bootstrap subsystem docs for the full option reference.

Development

pnpm install
pnpm build         # tsc → dist/
pnpm run test:ts   # vitest

Releases

Releases are automated with semantic-release: a merge to main computes the next version from the Conventional Commit history, publishes @rmartz/envctl to npmjs through OIDC trusted publishing (no npm token; tied to the release.yml filename), and only then tags it and creates a GitHub release. The publish runs as npm publish from @semantic-release/exec's prepare step (with @semantic-release/npm's own publish disabled) so a failed publish stops the release before any tag is pushed. Versions published before the move stay on GitHub Packages.