Skip to content
Abdifatah Artan
All projects

2025 — Maintained

Forge

A TypeScript-first CLI and SDK that automates release workflows, preview environments, and config drift detection for platform teams.

TypeScriptNode.jsCLIDeveloper Tools

Role — Creator & Maintainer

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:

commands/release.ts
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:

terminal
$ 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.

40+Adoptioneng teams using daily
180kDownloadsnpm, per month
-72%Release timemedian, measured
14xDrift alertsfaster detection

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.