Codifying developer intent into a CLI

The challenge: every project taxed its newcomers

The organisation's engineering estate spanned multiple projects across multiple frameworks and runtimes — multiple languages across customer-facing web services and internal workers, the specifics withheld under confidentiality. Each project had accumulated its own way of doing the same things. Spinning up a local environment on one project meant one set of conventions; on another, a different set; on a third, yet another approach requiring project-specific knowledge. Deployment varied in the same way.

The cost of this variation was invisible on any single project and substantial in aggregate, because it was levied at every boundary crossing. An engineer moving between projects paid it. A reviewer examining an unfamiliar codebase paid it. Most acutely, the organisation paid it whenever staffing had to change quickly: when additional engineers were assigned to an urgent project, roughly three days passed before a newly assigned engineer could get started — time spent decoding that project's particular commands, environment assumptions, and deployment path, on precisely the projects where days mattered most.

The underlying problem was one of interface. The tasks were identical across the estate — run this project locally, deploy this application, deploy this infrastructure — while the expression of those tasks differed everywhere. The engagement's premise was that the task vocabulary could be standardised without standardising the technologies underneath it.

The approach: standardise the interface, keep the stack

1. Discover what developers actually do, project by project

The work began with discovery rather than design: observing and interviewing engineers across projects to inventory the tasks they performed and the steps each project required for them. It covered a handful of active projects, with interviews focused on the technology leads who operated them. The notable finding was that even an estate this small had already diverged enough that the same task was performed differently on nearly every project — the tax was structural, not a symptom of scale. The inventory converged on a small set of universal tasks — local run, application deployment, infrastructure deployment — plus a long tail of project-specific operations that the standard interface would deliberately leave alone.

Discovery also established the baseline measure: the three-day figure for time-to-first-meaningful-change came from observing real onboarding onto an urgent project, and became the number the engagement would be judged against.

2. Convene the technology leads, and encode their consensus

A command that works "regardless of runtime" requires someone to decide what the correct behaviour is for each runtime. Those decisions were made by the people with standing to make them: the technology leads for each runtime were convened to agree what best practice looked like for their stack — how a service of each kind should be run locally, configured, built, and deployed. The CLI then encoded the consensus.

This sequencing did double duty. It produced technically sound defaults, since each was authored by the engineers most expert in that runtime. It also settled adoption in advance: the tool arrived as the leads' own agreed practice made executable, and the usual resistance to imposed tooling had little to attach to. Where leads disagreed, the questions were worked out in facilitated sessions; where consensus stalled, the chosen default and its rationale were written down as the agreed practice and left to be revisited only if it proved wrong in use.

3. Design the interface around tasks, with technology as a detail

The command grammar was organised by what the engineer intends, with the CLI resolving how that intent maps onto the project at hand:

• run local — start this project locally, whatever its framework or runtime. The CLI detected the project type and executed the runtime-appropriate procedure agreed by the leads.
• deploy app <helm-chart-name> — deploy an application through the standard Helm-based path.
• deploy cloud <terraform-deployment-name> — apply cloud infrastructure through the standard Terraform-based path.

The same verbs meant the same things everywhere. Knowledge acquired on one project transferred whole to the next, which is the property the three-day onboarding cost had been missing.

4. Implement thin: the CLI wraps the tools, and replaces none of them

The CLI was deliberately a thin layer over the existing toolchain — Helm, Terraform, and the per-runtime tooling continued to do the actual work, invoked with the agreed parameters and conventions. It was written in Go as a single distributable binary; each project carried a small declarative manifest (YAML) that named its type and parameters, from which the CLI resolved the runtime-appropriate procedure. The project-specific long tail was handled by a passthrough that let any project invoke the raw tools directly, so nothing the CLI did not model was blocked by it. This kept the tool small enough to maintain, preserved the teams' existing expertise in the underlying tools, and left an exit: any project could still be operated without the CLI, so the standard survived on convenience rather than enforcement.

5. Roll out by migration, and measure the result

Projects were brought onto the standard interface in waves. The rollout began with willing early-adopter teams, whose success built proof and internal advocates, and expanded from there across the estate, each migration accompanied by a short migration guide. Documentation collapsed correspondingly: per-project run-and-deploy instructions were replaced by a single reference. Most active projects migrated over the course of the rollout, and deployment practice converged on the standard paths.

The execution: sequence of the work

Phase one — discovery (the opening weeks). Task inventory across projects; baseline measurement; identification of the universal task set and the project-specific long tail.

Phase two — consensus (the following weeks, one runtime at a time). Technology leads convened per runtime; best practices agreed and recorded; the command grammar designed against the agreed task set.

Phase three — implementation (built iteratively against pilots). CLI built as a thin layer over Helm, Terraform, and the runtime toolchains. The technology leads who had authored the conventions dogfooded it on their own projects first, surfacing fixes before anyone else onboarded.

Phase four — rollout (in waves across the estate). Migration across the estate; documentation consolidated. Ownership then passed to an internal platform and tooling function, with documentation and a runbook, and the CLI was maintained in-house after the engagement.

What did not go smoothly

Parts of the rollout moved more slowly than planned.

Some local environments resisted the standard. A few projects' local setups did not fit the agreed procedure cleanly; rather than force a rewrite, they were accommodated through manifest extensions and the raw-tool escape hatch until they could be brought fully into line.

One runtime's consensus took several rounds. Agreeing best practice for one runtime took several sessions before the leads converged; it was resolved by documenting a default and proceeding, revisiting only if it proved wrong in use.

Some teams clung to the raw tools at first. Because the CLI was optional by design, a few teams kept using the underlying tools initially; they were won over by convenience rather than by mandate — slower to land than an enforced rollout, but stickier once it did.

The results

• Time to a first meaningful change on an unfamiliar project fell from 3 days to half a day — a sixfold reduction, measured on the same class of urgent-staffing event that produced the baseline
• One command surface across the estate: run local, deploy app <chart>, deploy cloud <deployment> behaved identically across all projects and runtimes
• Deployment practice converged on the standard Helm and Terraform paths — and new projects reached deployment faster, because developers could run test deploys themselves to confirm their Terraform and Helm charts behaved under the conventional commands before involving the platform engineering team to provision real staging and production infrastructure
• Cross-project mobility ceased to carry a tax: engineers moved between projects with their operational knowledge intact, and could be reassigned without a multi-day ramp-up — so urgent staffing changes no longer incurred the onboarding cost that produced the baseline

What this means if you're running a startup or SME

In short: when every project speaks its own dialect, the organisation pays a translation cost at every handoff — and the cost is largest exactly when speed matters most.

The remedy in this case had a specific shape. The standardisation targeted the interface, while each team's technology choices underneath were left intact — which is what made it affordable — and the standards themselves were authored by the technology leads, which is what made it adopted. Tooling imposed on engineers tends to be routed around; tooling that executes the engineers' own agreed practice tends to spread. The sixfold onboarding improvement followed from a modest tool encoding a well-run agreement.

This is the work we do at Aijutsu under our platform engineering practice: developer experience assessments, internal tooling, and the facilitation work — discovery, consensus among technical leads, rollout — that determines whether such tooling takes hold.

If assigning an engineer to a new project in your organisation costs days before their first meaningful change, that cost is measurable and reducible. Book a diagnostic conversation: [email protected]

Frequently Asked Questions

How do you reduce engineer onboarding time onto a project?

Standardise the operational interface of projects so that knowledge transfers between them. In this case, a single CLI made local run and deployment identical across every framework and runtime, and the time for an engineer to make a meaningful change on an unfamiliar project fell from 3 days to half a day.

What is a golden path in platform engineering?

A golden path is a supported, standardised route for common engineering tasks — running a service locally, deploying an application — that encodes an organisation's agreed best practice. In this case, the golden paths were expressed as CLI commands (run local, deploy app, deploy cloud) that behaved identically across all projects while invoking the appropriate toolchain underneath.

How do you standardise development across different frameworks and runtimes?

Standardise the task vocabulary while leaving the technologies in place. The approach in this case inventoried the tasks common to every project, had each runtime's technology leads agree the correct procedure for their stack, and built a thin CLI that mapped the common commands onto each runtime's agreed procedure.

How do you get engineering teams to adopt internal tooling?

Have the standards authored by the people they will bind. In this case, the technology leads for each runtime agreed the best practices the CLI would encode before it was built, so the tool arrived as their own decisions made executable — and adoption was further supported by keeping the CLI a thin, optional layer over tools the teams already used.

Should a company build an internal CLI or adopt an off-the-shelf developer platform?

The determining factors are the size of the estate and the specificity of the conventions. A thin internal CLI, as in this case, suits organisations whose value lies in standardising their own agreed practice over an existing toolchain (Helm, Terraform, runtime tools) at low maintenance cost; larger estates with self-service infrastructure needs may justify a fuller internal developer platform. The discovery-and-consensus work described here is required in either case.