Designing a CLI on the premise that an AI will drive it

Part 5 of 5 (finale) — series: Building a publishing tool, and shipping it. Last time was shipping with brew and scoop. See the series index. This time: designing the CLI on the premise that an AI drives it.

crofty is a plain CLI you type at the terminal. But one premise of its design is a little different.

“A person installs crofty and does the first setup; after that, their AI (an agent) runs it.” That’s the usage it assumes. Rather than a person remembering and typing commands every time, an agent drives crofty on their behalf — and the build is meant not to get in the way when it does.

When you include an AI among the operators, how does CLI design change? The series finale is about that.

The window is the output, not a click

People and agents can do different things. A person can click a screen and read documentation. An agent can’t click, but it can run a command and read the output.

From that difference, the center of gravity shifts from “the screen” to “the output text.” So crofty builds no GUI, no admin panel. Instead, it puts its effort into making command output a window both people and agents can read. Concretely, three things.

1. What it can do is just an ask away

Rather than burying capabilities deep in the docs, you let people — and agents — ask the tool itself.

What an agent wants first is “which commands exist, and how do I use them.” crofty agent returns that whole picture at once — the commands and their flags, the usual order, and the surfaces for reading state. It’s the one page to hand an AI first; run it, and it can start moving on its own.

From there, more focused views. crofty features returns “what you can do, and how to turn each thing on.”

$ crofty features
crofty features — what you can do, and how to turn each thing on.

Out of the box (works in a fresh project):
    rss        an Atom/RSS feed and a 'Follow by RSS' link
               → automatic — nothing to set
    share      reader share buttons, and `crofty share` …
               → automatic on posts; `crofty share <path>` for authors

Restyle (owned, contract-safe):
    looks      ready-made colour/type presets (quiet-paper, …)
               → crofty theme set <name>

Each line pairs “what you can do” with “how to turn it on.” Type crofty config and it returns “how things stand right now” the same way. Each is a window — for a person or an AI — to start moving without hunting through docs.

2. Print the next move, every time

Commands write not just the result but “what to do next” into the output. After a build, for instance:

$ crofty build
✓ built → ./dist
next:
  crofty preview     # look at it locally first (no account)
  crofty deploy      # put it online (connects a free Cloudflare account)

With next: there, you don’t have to remember the steps — follow the output and you move on. A kind hint for a person; a cue for an agent. There’s also a machine-readable mouth, like adding --json to share output.

3. Don’t rewrite things — show them

crofty writes the files it owns, but it doesn’t quietly rewrite yours — hugo.yaml, say. Instead it guides: change this, here.

This helps people and agents alike. What’s about to happen, and what you should change, is visible in the output, so it never becomes a black box. A tool that doesn’t change state on its own is also one you can hand to an agent without it running away.

In short

Include an AI among the operators, and CLI design leans from “a click” toward “text you can read, ask, and find the next move in.” Instead of building a GUI, make the output itself the best window. That’s the shape crofty chose.

And that’s the end of all five parts. I built a thin pipeline for owning what you publish, contracted the output so the inside stays changeable after shipping, designed for multiple languages, shipped with brew and scoop, and tuned it so both a person and an AI can drive it. If it helps in some single corner for someone making a small tool and giving it away, that’s plenty.

← Previous: Shipping a CLI with brew and scoop　|　That’s the end of the series.