I found this in a terminal transcript, not a bug report:
$ circleci run trigger --help | head -40
I hadn’t asked for head -40. Claude added it, and it does that constantly; help output is untrusted input of unknown size, and pulling an unbounded page into a context window is a bad trade. Forty lines is the interface. Below line 40 was the part that tells you how to use the command.
Hypothesis
As I shared in a previous blog post, when I started rewriting the CLI, I already understood we were writing for agents; that was the premise of the rewrite. Every data-returning command has --json with its fields enumerated, and the command tree generates an MCP server, so each command’s description is a tool description.
Two things we didn’t know:
We didn’t know there was a length limit, so we never measured against one (”written for agents” was a set of content decisions, and none of them had a size).
We didn’t know that we were saying everything three times: the accepted values for
--event-preset, the default for--provider, all of it in the examples, in the flag table, and again in the prose. Each section had been written to stand on its own, and nobody diffs a paragraph against a table.
So the fix wasn’t “write less”. If the length was repetition, most of it would come out mechanically; and if prose went last, truncation would cut the cheapest content rather than the most expensive.
Setup
I measured before editing anything, because “is this help text too long?” is otherwise a taste argument nobody wins. Walk the command tree, render every page the way a real invocation would, and count. Not total lines, but whether each section finishes inside the first 40. A flag table that starts on line 38 isn’t visible; it’s a teaser.
Across 169 command pages, the mean was 49 lines, the worst 91, and only 15% got their examples inside the window (the section an agent actually copies from).
Three passes. Boilerplate out: the banner, the per-page table re-printing the same four global flags, the repeated “Learn More” links. Seventeen lines a page, no prose rewritten. Reorder: Short → Usage → Arguments → Flags → Examples → Details, so truncation eats prose first. Trim the duplication, never dropping a flag row or an example to make space. project trigger create went from 91 lines to 42.
Then keep it fixed. Order and boilerplate are properties of the help template now; length is a test that asserts every page fits 40 lines, with individual caps for the twenty-five commands that genuinely can’t, and those caps only ratchet down. And since these commands are largely written by an agent working from guidelines in the repo, the rule went there too.
The PR: https://github.com/CircleCI-Public/circleci-cli/pull/1667. 449 files, about 2,600 net lines of help text deleted.
Results
The three passes cut both the mean and the worst case, but what really matters is whether the sections an agent actually uses (flag table and the examples) finish rendering before truncation. A page that runs to 70 lines but front-loads its flags is a better interface than a 45-line page that buries them. The reorder pass was designed around this: put the cheap content last, so if something gets cut, it isn’t the part Claude copies from.
No task-success delta, because I don’t have one. What changed is the interface: every command’s complete flag list now sits inside the window an agent reads, and three in four get their examples there too, against one in seven before. The old failure mode was silent, which is why it lasted. Claude wasn’t erroring; it was succeeding at a degraded version of the task on whatever fragment of the flag list it had seen. Worse than a stack trace, because nothing tells you to go and look.
TL;DR
“Designed for agents” is a budget, not a style. We had the content decisions right and still shipped help that couldn’t be read, because we never asked how much of it arrives.
Pick one canonical place for each fact. The duplication wasn’t sloppiness; it was three self-sufficient sections maintained separately. The flag table is canonical now, and prose restating it is a defect.
Make it a test. A style guide asking for 40 lines would have lasted a month; the next person adding a command, human or otherwise, has no reason to know the number exists.
The pages are better for humans now, which I didn’t expect; not because agents and people want the same thing, but because neither mistake was agent-specific. Nobody benefits from reading a flag’s values three times, and nobody was reading line 70 either.
