Unify the CLI as noun-verb commands: sessions, tools, events

[V3RON]

Why

The CLI mixes three command shapes. daemon status|stop is noun then verb. ls, revoke, link, invoke are bare verbs. tools [selector] [name] and events [selector] are nouns whose positional argument doubles as a selector, so listing and acting share one word and the first positional is ambiguous (packages/appduct/src/cli/command-options.ts:128). The cost lands in three places:

• Agents cannot guess a command from its neighbours. Knowing appduct tools says nothing about appduct ls or appduct invoke, so the shipped skill has to spell out every form.
• New listings have nowhere natural to go. Let apps declare the events they post, and let agents list them #95 needs a flag, appduct events --list, because a bare appduct events ls would parse ls as a session selector. appduct events --since is likewise a mode switch on a streaming command.
• Selector placement differs per command, so --help output is the only way to learn each one.

Expected outcome

Every command is appduct <noun> <verb> [selector] [args], with daemon as the model:

• appduct sessions ls | revoke [selector] | link [...] replacing ls, revoke and link.
• appduct tools ls [selector] [--full|--groups|--group|--filter|--limit|--offset] | describe [selector] <name> | call [selector] <name> --input ... [--timeout] replacing tools, tools <name> and invoke.
• appduct events tail [selector] | since [selector] <cursor> replacing events and events --since. events ls is reserved for the catalog from Let apps declare the events they post, and let agents list them #95.
• daemon, init, keygen, doctor and mcp keep their shape; the last four are one-verb nouns already.

This is a clean break, with no aliases: we are pre-1.0. A removed form fails with a usage error that names its replacement, so an agent working from an old prompt can correct itself in one step. --json data does not change, so scripts that parse output only need the command renamed. The shipped skill, the READMEs, website/, docs/ and the CLI's own hints all switch to the new forms.

Shape: routes/sessions/, routes/tools/ and routes/events/ become routers like routes/daemon/, one route per verb. tools describe and tools call take [selector] <name> through splitSelectorAndRequiredTarget, and splitOptionalSelectorAndTarget is deleted. cac matches only the first word and reads flag types from that command, so each noun command in create-cli.ts declares every option its verbs use. The keys in output.ts's renderSuccessData become the new paths. The root router's unknown-command error carries a map from each removed form to its replacement.

Constraints and non-goals

• No RPC or daemon change: this is cli/ routing and docs only.
• Exit codes, --json data, global flags and selector semantics stay as they are. Under --verbose, meta.command reports the new name ("tools ls").
• Non-goal: renaming the MCP tools (appduct_list_tools and friends already follow a verb-noun pattern of their own).
• Non-goal: changing what any command does. That rules out sessions describe here; file it separately if it's wanted.
• Non-goal: --name on events tail/since, which Filter app events by name glob and bound payloads on every surface #94 adds to the new verbs.
• Let apps declare the events they post, and let agents list them #95's CLI criterion becomes appduct events ls.

How we know it is done

1. appduct sessions ls, sessions revoke [selector], sessions link [flags], tools ls [selector] [flags], tools describe [selector] <name>, tools call [selector] <name> --input '{}', events tail [selector] and events since [selector] <cursor> each produce the same stdout, exit code and --json data as the command they replace. SIGINT during tools call cancels the call as it does for invoke today, and events since prints the trailing cursor line.
2. appduct ls, revoke, link and invoke exit 64 with a message naming the new form, e.g. Unknown command "ls"; use "appduct sessions ls".
3. appduct sessions, appduct tools and appduct events with no verb, or with an unknown verb, exit 64 naming that noun's verbs, like appduct daemon does. With --help they print the verbs and exit 0.
4. Until Let apps declare the events they post, and let agents list them #95 lands, appduct events ls exits 64 naming tail and since.
5. A boolean flag placed before a positional does not swallow it: appduct tools ls --full <selector> and appduct sessions link --qr --open ios-sim parse as intended.
6. The shipped skill, both READMEs, website/, docs/ (including ARCHITECTURE.md §10) and the CLI's own hints (output.ts, commands/init.ts) use only the new forms, and the CLI integration tests run against them.
7. A Breaking changelog entry maps each old form to its new one.

Alternatives considered

• Keep bare verbs and add flags per listing (events --list): works, but leaves three command shapes and the positional ambiguity.
• Deprecated aliases for a release: rejected. We are pre-1.0, and aliases would need a fallback router, legacy routes and a notice that stays silent under --json, all for one release.
• Verb-noun (appduct list tools): reads well but does not match daemon status, the one noun-verb command already shipped.

[V3RON]

Question: approve this design?

Design

Premise, checked against main (629d161). It still holds. What changed since filing: #93 has landed. --name (#94) and events ls (#95) are still unbuilt, so neither ships in these slices. tools also takes --full and --groups, which the issue leaves out; both move to tools ls. No MCP tool description names a CLI command. The old forms appear in the skill, both READMEs, 13 website/ pages, docs/, and the human hints in output.ts and commands/init.ts.

Goal. Every command is appduct <noun> <verb>. The old forms keep working during a deprecation window and name their replacement.

Shape. Only cli/ changes. commands/, the RPC and the --json data stay as they are.

• routes/sessions/, routes/tools/ and routes/events/ become routers like routes/daemon/, with one route per verb, each moved from today's route. tools describe and tools call use splitSelectorAndRequiredTarget. The ambiguous splitOptionalSelectorAndTarget remains only in the legacy tools route.
• router.ts gets two additions, each with two or more callers:

  type RouterOptions = { unknown: ...; fallback?: RouteLoader } // tools, events: no verb matched
  export const deprecated = (replacement: string, load: RouteLoader): RouteLoader
  // one stderr line: "`appduct ls` is deprecated; use `appduct sessions ls`. Removed in <release>."

  In the root table, ls, revoke, link and invoke become deprecated(...) over the new verb routes. The tools and events routers set fallback: deprecated(..., <today's route, unchanged>). Removing the aliases later means deleting those entries and files.
• create-cli.ts: cac matches only the first word, and it builds its boolean/string table from that command's options. So each noun (sessions [...args], tools [...args], events [...args]) declares every option its verbs use. Without that, --qr, --full and --groups would swallow the next positional. The noun's description lists its verbs, and that is what --help prints.
• The keys in output.ts's renderSuccessData become the new paths ("tools ls", "tools call" and so on).

It adds no port and no event. Every step is a call.

Not in scope. sessions describe is new behaviour, and the issue lists changing behaviour as a non-goal, so it should be filed separately if wanted. --name on tail/since comes with #94. A working events ls comes with #95.

Slices

1. sessions (proves the router and alias mechanism)
   1. sessions ls, sessions revoke [selector] and sessions link [flags] match the old commands' output, exit code and --json.
   2. ls, revoke and link still work and print one stderr line naming the new form.
   3. appduct sessions, appduct sessions --help and an unknown verb (exit 64) all list ls, revoke and link.
   4. The docs and init's hint use the new forms, and a changelog entry is added.
2. tools
   1. tools ls [selector] [--full|--groups|--group|--filter|--limit|--offset], tools describe [selector] <name> and tools call [selector] <name> --input match what they replace. SIGINT cancels tools call.
   2. tools, tools <name> and invoke still work and print the notice.
   3. tools --help lists the verbs.
   4. The output hints and docs switch to the new forms, and the changelog entry is amended.
3. events
   1. events tail [selector] and events since [selector] <cursor> match events and events --since, including the cursor line.
   2. events and events --since still work and print the notice.
   3. events ls exits 64 and names tail and since, until Let apps declare the events they post, and let agents list them #95 lands.
   4. The docs and changelog are updated.

Decisions needed

1. When the aliases are removed. We are on 0.12.0, so "next major" means 1.0. I recommend removing them in 0.14.0 and saying so in the changelog.
2. The notice under --json. The version-drift notice is suppressed under --json. I recommend printing this one anyway: stdout stays a single object, and scripts are the callers that most need the warning.
3. Bare tools and events. During the window they stay aliases, so criterion 4 (a bare noun lists its verbs) holds for them only after removal. sessions meets it right away.
4. Words that become verbs. A selector or tool name spelled like a verb now parses as the verb. For example, old tools call, meaning a tool named call, becomes a usage error, and the way to reach it is tools describe call. I recommend accepting this.
5. meta.command. Under --verbose it reports the new name, including when an alias ran.

Risk. If #95 goes ahead on events --list first, slice 3 makes events ls the real command and turns --list into an alias.

---

Generated by Claude Code

[V3RON]

This supersedes the design above. We decided on a clean break: no aliases, since we are pre-1.0. A removed form fails with exit 64 and names its replacement. The change ships as one PR.

Without aliases, this fits one PR in one package with no wire change, so it doesn't need slices. I've rewritten the issue body with the final shape and criteria and moved it to status:ready.

---

Generated by Claude Code