Work / Cartograph
Cartograph · Developer tools · Remote

A CLI engineers actually want to use.

Replacing Cartograph's tangle of internal scripts with a single, well-tested CLI — plus the tooling to keep it small as the team grew from 12 engineers to 40.

10 weeksDuration
3 engineersTeam
2025Shipped
Go · Cobra · CIStack
Outcome

The numbers, six months after launch.

11 → 1
Internal scripts consolidated into a single, discoverable binary.
< 50ms
Cold-start time for every subcommand — a hard budget we never broke.
1,200+
Weekly invocations across the team six months after launch.

01 · The context

Cartograph is a mid-stage startup building observability tooling for data teams. By the time we were introduced, their internal tooling had grown into eleven separate scripts, half of them only one engineer could reliably run. New hires lost a full week figuring out how to release a patch.

The goal wasn't cleverness. It was to make the common paths boring: release, rollback, hotfix, smoke-test, generate fixtures. If a junior engineer couldn't do each in one command on their first day, we hadn't finished.

The real problemScripts proliferate because writing a new one is cheap. Consolidating them is the opposite. We needed a CLI that was pleasant enough to use that nobody felt the urge to fork off a private helper.

02 · The approach

We started by cataloguing every invocation of every existing script over the prior 90 days. That gave us the minimum viable surface. From there, we designed the CLI around three principles: every command is idempotent, every command prints a plan before it acts, and every command has a --dry-run that exits 0 when things look fine.

Cobra was the obvious Go choice. What we built around it was the interesting part: a retry budget, a structured error surface, and a "what would happen" planner shared across commands. That code later became resilient-cli.

"We stopped writing one-off scripts. Nobody told them to. The CLI was just better."

03 · The architecture

The CLI is a single statically-linked Go binary, distributed via a self-update channel that's gated on a short-lived token from Cartograph's SSO. Each subcommand is its own package with its own tests. A shared planctx ties plan-then-apply across the lot.

// A subcommand is just a plan + an apply.
type Command interface {
Plan(ctx *planctx.Context) (Plan, error)
Apply(ctx *planctx.Context, p Plan) error
}
// --dry-run short-circuits before Apply is called.

Every run writes a structured audit record to the team's datastore. Six months in, those records became the input to a small dashboard that shows which commands get used, which fail most often, and which are overdue for love.

04 · The outcome

We shipped v1.0 in week ten, with eleven legacy scripts removed and a deprecation schedule agreed with the team. Six months later, the binary is still the primary interface every engineer uses to ship — and the commit log has fewer than forty changes on it. That's the sign we built something durable.

Along the way, we extracted the retry and planning primitives into resilient-cli, now used by a handful of other teams we've never met. That's how open source should work.

Next case study

A Postgres migration that stopped paging the on-call.

Read Lumen →