Repository navigation
feat(cli): finish the <noun> <verb> command-surface sweep for min and mip #1005
Description
Summary
Finish the move to a consistent <noun> <verb> command surface across min
and mip. #976 landed the
first slice (package); the rest of the surface — sessions, completions, and
the naming of the runnable unit — is still shaped by history, and the decision
to converge on <noun> <verb> is not recorded anywhere in the repo.
Origin: Slack thread, #eng 2026-07-24
("Revisiting the subcommand for package builds"). Consensus in that thread:
option (2) — a noun-first hierarchy — with the explicit follow-on that we
"ideally move to a consistent min <noun> <subcommand> style for most things".
Already landed (#976)
mip build/mip test/mip shellshorthands removed; the way to run a
task namedbuildismip run build.mip package(aliasespkg,packages) withbuild,dep, and hidden
build-plan,patched-build,upload-cache.min build→min package build;min patched-pkg→min package patched-build.
What remains
1. Noun-first grouping for the session surface
min's session commands are still bare verbs at the top level:
min ls | activate | attach | destroy | rename | stop
Under the agreed convention these become a session noun with shared verbs
reused across nouns (list being the obvious one — cf. min loadout list,
which already has the right shape, and the min providers list /
min sessions list examples raised in the thread):
min session list | activate | attach | destroy | rename
Decided (Norrie, 2026-07-28):
- Top-level aliases:
min lsand baremin(resolve-and-attach) stay as
they are. They are high-traffic and the break isn't worth it; they are
documented exceptions, not accidents. stop: it stops the daemon/backend, not a session, so the noun is
provider—min provider stoplong form, withmin stopretained as the
shortcut.- Project-configuration passthroughs:
min init,min add,min update
stay bare.
2. Singular/plural aliasing as a stated convention
package/packages/pkg already alias. Make that the documented rule for
every noun we introduce (session/sessions, loadout/loadouts,
provider/providers) rather than a per-command accident.
provider becomes a real noun as a result of the stop decision above, so it
needs the same treatment: min provider list alongside min provider stop.
3. min completions install <shell>
min completions <SHELL> writes a registration shim to stdout; all the
bookkeeping — target dirs per shell, atomic write, unwritable-dir tolerance,
zsh zcompdump invalidation, install-record entry — lives in the installer
(scripts/install.sh:739-780). That logic is unavailable to anyone who did not
install via curl | sh.
Proposed shape:
min completions print <shell>(today's behaviour, kept for
source <(...)use)min completions install <shell>— the installer's logic, in the binary
with scripts/install.sh delegating rather than duplicating. Same question
applies to mip completions.
4. Unresolved: what the runnable unit defined in minimal.toml is called
The thread bikeshedded sandbox vs session vs task without landing:
sandboxis precise ("isolated runtime environment") and reads naturally as
a noun inmin sandbox run <name>, but externally connotes isolation, not
execution.sessionoverlaps with other industry uses and with our own daemon-side
session objects.taskwas the prior name and carries a non-interactive connotation.
This blocks the concrete shape of the run path (min sandbox run claude-session
vs min task run … vs staying with min run <task>), so it needs a decision
before the sweep in (1) can be specified. Worth doing as an explicit
terminology call rather than another thread.
Non-goals
- Re-litigating #976. Its
decisions stand. - The
minimald/minvmdcommand surfaces.
Acceptance criteria
- The
<noun> <verb>convention (including singular/plural aliasing) is
written down —docs/reference/cli.mdor an ADR — not just implied by the
command tree. min's session surface matches the convention, with any retained top-level
aliases documented as deliberate ergonomic exceptions.min completions install <shell>exists andscripts/install.shcalls it
instead of carrying its own copy.- The runnable-unit terminology is decided and applied consistently across
min,mip,minimal.toml, anddocs/. docs/reference/cli-min.mdanddocs/reference/cli-mip.mdregenerated.
Timing
Agreed in-thread that this should land before the repo opens, so early adopters
aren't handed a renamed CLI shortly after picking it up. Every item here is a
breaking change to the user-facing surface; the cost of deferring is paid by
users, not us.
Activity
norrietaylor commentedon Jul 29, 2026
Fanned out into two PRs, both covering the decisions recorded in the body above:
sessionandprovidernouns, plus the naming convention written intodocs/reference/cli.md. Verified withjust ciandjust e2e(the VM-backed session e2e is the check that matters, sincescripts/session-e2e.shdrives the renamed commands for real).min completions print/min completions install, withscripts/install.shdelegating to the binary. Verified withjust test-installerplus a by-hand exercise of the real binary against throwawayHOMEs.Still open on this issue after those land:
sandboxvssessionvstaskfor the thing defined inminimal.toml). Undecided, and it gates the shape of the run path (min sandbox run <name>vsmin task run …vs stayingmin run <task>). This needs an explicit call, not another thread.min provider list—provideris a real noun as of #1008, so listing backends is now a small follow-up.mip completions— still the old single-verb shape; sameprint/installtreatment applies.feat(min)!: re-parent session verbs under session and provider nouns
feat(min)!: split completions into print and install verbs
feat(min)!: split completions into print and install verbs
fix(min): make the completions singular alias visible in help
refactor(min): keep stop top-level, drop the provider noun
feat(min)!: re-parent session verbs under the session noun
feat(min)!: re-parent session verbs under the session noun
feat(min)!: split completions into print and install verbs
fix(min): make the completions singular alias visible in help
feat(min)!: re-parent session verbs under the session noun (#1008)
feat(min)!: split completions into print and install verbs (#1009)