# The CLI is the product

*2026-08-15 · Design Journal*

For several months, ConnectOnion accounts have been able to send credits to each
other. `POST /api/v1/transfers` worked in production. `GET /api/v1/transfers`
returned clean history. Onboard verification was built on top of it. The
feature was live, tested, and billing real money.

It also, for every user we have, did not exist.

Nothing in `co --help` mentioned transfers. No command called the endpoint. The
only way to move credits was to hand-sign a request against the API — which is
to say, the only users of the feature were the people who built it. A working
backend with no CLI in front of it is not a shipped feature; it is a rehearsal
for one. The library is the engine, but the skill and the CLI are the
interface, and users — human or AI — live entirely on the interface side.

This release closes three gaps of exactly that shape. Each one is small. What
makes them worth a journal entry is that all three were invisible from where we
usually stand.

## An error that names a problem no command can answer

When multi-address accounts shipped, `co email send --from` gained a guard: try
to send as an address you don't own and the server answers 403 with

```
❌ Failed: nobody@mail.openonion.ai is not one of this account's email addresses.
```

That message is accurate, specific — and a dead end. It names a category
("this account's email addresses") that no command in existence could list.
The backend's `list_email_addresses()` was live; the CLI never called it. An
agent hitting that error had nowhere to go but guessing, and an agent that
guesses email addresses is an agent you eventually have to apologize for.

The fix is `co email addresses`, and one sentence appended to the 403: `See
your addresses: co email addresses`. The error is now a fix-it guide. That is
the whole standard we're trying to hold: every failure message should read as
the first line of its own recovery procedure.

## Tips that hid from the callers who needed them

Our listing commands end with a next-step tip — `Read one with: co gmail read
<#>`. The tip lived inside `if console.is_terminal:`, so piped output didn't
get it. That guard felt reasonable when it was written: pipes are for scripts,
scripts don't read prose.

Except the callers who pipe are AI agents, and they do read prose — it is the
only thing they read. A human in a terminal has habits, history, and the
memory of yesterday's session. A fresh agent has the output in front of it and
nothing else. We had built discoverability for the audience that needs it
least and stripped it from the audience that needs it most, and no manual test
could ever catch it, because a human tester is by definition in a terminal.

## Measuring the tips instead of admiring them

The `cli-skill-design` methodology gives tips an actual test: hand a fresh,
text-only model one command's output and a goal, and ask for the single next
shell command. No SKILL.md, no `--help`, no history — those are the crutches
the tip exists to replace.

The first run across the mail surface scored **5 of 8**. The three failures:

- A piped inbox printed no tip at all, and the model invented `readmail 18f2a`.
- A failed send said `Retry the same command with --idempotency-key <key>` —
  but "the same command" is not in the output, so there was nothing to
  reconstruct the retry from. The model replied `!! --idempotency-key k-123`.
- The stale-number message said `run co gmail to refresh` and stopped one step
  short of the goal. The model replied `co gmail && co gmail 3`, the second
  half of which does not exist.

None of these tips looked wrong in review. All of them read fine to a human,
because a human silently fills the gap with context the tip was supposed to
carry. That is precisely why the test uses a model with no context: it can't
be polite about a missing step.

The fixes are one line each. Tips now survive piping. The retry hint restates
the entire command, quoted and copy-pasteable. The stale-number message names
the step after the refresh. On the re-run, all eight tips — plus the new
transfer and addresses tips — produced a correct next command.

## What this teaches

The three gaps share one anatomy: **the engine was done and the interface was
not, and from the engine room everything looked finished.** The transfer API
passed its tests. The ownership 403 was correct. The terminal tips worked for
everyone who tried them by hand. Every instrument we normally read said green,
because every instrument we normally read measures the engine.

The interface has its own instruments, and they are unforgiving in a useful
way: does `--help` name the capability? Does the failure name the next
command? Does the output, alone, carry a fresh agent to the right next call?
Those questions have runnable answers, and running them found real defects
that review had blessed.

So the rule we're keeping: a feature ships when the CLI exposes it, the errors
route around themselves, and the tips pass the test — not when the endpoint
returns 200. The skill and CLI are the interface; the library is the engine.
Nobody buys an engine.