Your CLI's heaviest user is an agent

The user changed. The tool did not.

Creator Notes has a CLI. You can list notes, build canvases, search the workspace, and link ideas from a terminal. It looks like a tool for a person: terse flags, a help page you read once, the occasional spinner.

But look at who actually drives it. Most calls to the Creator Notes CLI today come from AI agents: Claude Code, Codex, Cursor, running it dozens of times in a single session. The human is in the loop, but the hands on the keyboard are usually an agent's.

That audience has its own ergonomics. People have started calling it agent experience, or AX. It is not the same as developer experience, and the two can quietly pull in opposite directions.

Humans and agents want opposite things

Once you start designing for the agent, the trade-offs flip. The same decision that helps a person can cost an agent tokens or correctness.

Help: read once vs read every time

A human reads --help once and remembers it. An agent re-reads it at the start of every session and needs it short, with a runnable example it can copy.

Output: scan vs parse

A human scans a formatted table. An agent parses JSON and needs a stable shape, no color codes, and no surprise truncation.

Failure: read vs branch

A human reads the error and retries by hand. An agent branches on the exit code and needs the message to say what to do next, not just what went wrong.

Verbosity: free vs taxed

A human does not care how many characters a list command prints. An agent pays for every one of them, out of a finite context window.

The checklist we scored against

We did not want to guess. We pulled the current thinking on agent-friendly CLIs: Anthropic's guidance on writing tools for agents, the emerging AXI principles, and the benchmarks comparing command-line tools to MCP servers. It converges on roughly fifteen properties. Structured output as a first-class mode. Semantic exit codes. Errors with an actionable hint. Self-describing help with examples. A way to discover the schema instead of guessing. Batch operations to avoid N+1 round-trips. Token-efficient output. Auth from an environment variable. No ANSI when piped.

One finding was worth pulling out on its own. For most agent tasks, a well-shaped CLI beats an MCP server by a wide margin: something like 10 to 35 times cheaper on tokens, and far more reliable in published benchmarks (roughly 100 percent vs 72 percent). MCP loads every tool's schema into the model's context up front. A CLI is discovered lazily, one help page at a time, and models already know shell syntax cold. The lesson was not “drop MCP.” It was: the CLI is the leverage point. Invest there, and keep the MCP server a thin wrapper over the same commands.

Then we scored our own CLI against the list. It came out around 6.7 out of 10. Strong where it counted, weak in a few specific, fixable places.

What we changed

Exit codes that mean something

0 for success, 2 for auth, 4 for not found, 5 for conflict, 7 for permission. An agent can branch on the number instead of grepping the message.

Errors that tell you what to do next

Every error now carries a hint. “Note not found” arrives with the fix attached, which collapses a guess-and-retry loop into a single call.

$ cn notes get MEETING-999
Error: Notes not found: MEETING-999
  hint: Run `cn notes list` to see valid display IDs in this workspace.
$ echo $?
4

Help with examples, everywhere

Every command ends with a runnable example, and the top-level help fits the exit codes and environment variables on a single screen.

One call to learn the workspace

A new cn schema command returns the note types, the relationship vocabulary, and the resource shapes in a single compact document an agent reads once and caches for the rest of the session.

$ cn schema --json
{
  "workspace": { "id": "...", "name": "Creator Notes", "verified": true },
  "types": [{ "name": "Insight", "prefix": "INS" }, ...],
  "relationships": { "common": ["references", "supports", "blocks", ...] },
  "exitCodes": { "0": "ok", "4": "not found", "5": "conflict", ... }
}

A bug only an agent would hit

cn notes list --limit 5 --json was silently returning the entire workspace. A human never noticed, because the human-facing table did truncate. The agent got everything and paid for it in tokens. Now the limit applies in JSON too, and truncation is signalled.

Output you can trim

A --fields flag projects results down to the keys you actually need, so a list call does not spend context on fields the agent will ignore.

The part the checklist misses

The standard advice for destructive actions is a --dry-run flag: let the agent preview the change before it commits. We took a different route, and we think it is better.

Every change an agent makes to a canvas is bracketed as an agent run: a snapshot before, the granular per-item diffs, and a snapshot after. The change applies immediately. It shows up as a single entry in the canvas history. If it is wrong, a human reverts the entire run with one button.

For an agent that was going to commit anyway, “do it, then undo if it is wrong” beats “preview, decide, then do.” It costs fewer tokens, and a human reviewer sees the real result on the canvas instead of squinting at a predicted diff.

Dry-run asks the agent to imagine the outcome. Revert lets it find out, safely.

We will be honest about the edge: today this covers canvas operations. Extending the same one-click revert to bulk note operations is the next thing on the list.

What we are taking from this

Agent experience is going to matter the way developer experience started to matter a decade ago. The tools that win the agent era will be the ones an agent can drive without guessing, without wasting tokens, and without a human hovering over the undo button.

A CLI turns out to be a good shape for that. Models already know how to use one. The cost per call is small. And nearly every change we made for the agent made the tool nicer for the human too: clearer errors, better help, less noise.

We are not finished. But the Creator Notes CLI is now something we would hand to an agent and trust it to use.

Point an agent at a real workspace.

Create a workspace, give your agent the CLI, and let it read, write, and organise alongside you. The same context, visible to both of you.