Why another CLI?#
Every platform team I'd worked on had built the same three tools badly: a release helper shell script, a preview-environment hack, and a drift checker nobody trusted. Forge collapses those into one command surface with a real type system behind it.
The design bet: the CLI should be a thin, pretty layer over an SDK people can import. Scripts become reviewable TypeScript instead of opaque bash.
The command surface#
Commands are declared as typed objects, and help text, argument parsing, and completions are all derived from the same declaration:
import { defineCommand, z } from "@aartan/forge";
export const release = defineCommand({
name: "release",
description: "Cut a release and ship it through the pipeline",
args: {
version: z.string().regex(/^\d+\.\d+\.\d+$/).describe("Semver version"),
notes: z.string().optional().describe("Release notes file"),
},
flags: {
dryRun: z.boolean().default(false),
env: z.enum(["staging", "production"]).default("staging"),
},
async run({ args, flags, log }) {
const plan = await buildReleasePlan(args.version, flags.env);
if (flags.dryRun) {
log.plan(plan);
return;
}
log.start(`Releasing ${args.version} to ${flags.env}`);
await executeRelease(plan, log.progress());
log.success(`Shipped ${args.version} in ${plan.duration}s`);
},
});The same defineCommand object powers forge completions for zsh and fish,
so flags and choices never drift from the implementation.
Config drift detection#
The feature that made Forge sticky was forge check — it diffs the deployed
configuration of an environment against the repo's desired state and renders a
reviewable plan:
$ forge check --env production
✓ 12 resources in sync
~ 2 resources drifted
service/checkout-api
image: v142 → v147
memory: 2Gi → 4Gi
cron/export-nightly
schedule: 0 2 * * * → 0 3 * * *DX details compound
Prompts that reprint exactly the command they'll run, --dry-run on every
mutating command, and monospaced plan diffs — each is a small thing, together
they're why teams trust a tool with their production releases.
Lessons#
- Treat the SDK as the product. The CLI got the attention, but the SDK is what let teams delete their bespoke scripts.
- Zod schemas as a single source of truth — parsing, help text, and completions from one declaration removed a whole class of documentation bugs.
- Measure the boring metric. Median release time falling 72% is a better adoption story than any feature we shipped.