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 shell shorthands removed; the way to run a
task named build is mip run build.
mip package (aliases pkg, packages) with build, 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 ls and bare min (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 stop long form, with min stop retained 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:
sandbox is precise ("isolated runtime environment") and reads naturally as
a noun in min sandbox run <name>, but externally connotes isolation, not
execution.
session overlaps with other industry uses and with our own daemon-side
session objects.
task was 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 / minvmd command surfaces.
Acceptance criteria
- The
<noun> <verb> convention (including singular/plural aliasing) is
written down — docs/reference/cli.md or 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 and scripts/install.sh calls it
instead of carrying its own copy.
- The runnable-unit terminology is decided and applied consistently across
min, mip, minimal.toml, and docs/.
docs/reference/cli-min.md and docs/reference/cli-mip.md regenerated.
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.
Related
- #976 — the package slice
(merged)
- #636 — epic: finalize the
minimald/min command surface for Minimal One; this is a concrete child of
its "user-facing terminology audited and stabilized" outcome
- #972 —
min login missing
from the CLI reference (same docs surface)
Summary
Finish the move to a consistent
<noun> <verb>command surface acrossminand
mip. #976 landed thefirst slice (
package); the rest of the surface — sessions, completions, andthe 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 atask named
buildismip run build.mip package(aliasespkg,packages) withbuild,dep, and hiddenbuild-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:Under the agreed convention these become a
sessionnoun with shared verbsreused across nouns (
listbeing the obvious one — cf.min loadout list,which already has the right shape, and the
min providers list/min sessions listexamples raised in the thread):Decided (Norrie, 2026-07-28):
min lsand baremin(resolve-and-attach) stay asthey 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 isprovider—min provider stoplong form, withmin stopretained as theshortcut.
min init,min add,min updatestay bare.
2. Singular/plural aliasing as a stated convention
package/packages/pkgalready alias. Make that the documented rule forevery noun we introduce (
session/sessions,loadout/loadouts,provider/providers) rather than a per-command accident.providerbecomes a real noun as a result of thestopdecision above, so itneeds the same treatment:
min provider listalongsidemin provider stop.3.
min completions install <shell>min completions <SHELL>writes a registration shim to stdout; all thebookkeeping — target dirs per shell, atomic write, unwritable-dir tolerance,
zsh
zcompdumpinvalidation, install-record entry — lives in the installer(
scripts/install.sh:739-780). That logic is unavailable to anyone who did notinstall via
curl | sh.Proposed shape:
min completions print <shell>(today's behaviour, kept forsource <(...)use)min completions install <shell>— the installer's logic, in the binarywith
scripts/install.shdelegating rather than duplicating. Same questionapplies to
mip completions.4. Unresolved: what the runnable unit defined in
minimal.tomlis calledThe thread bikeshedded
sandboxvssessionvstaskwithout landing:sandboxis precise ("isolated runtime environment") and reads naturally asa noun in
min sandbox run <name>, but externally connotes isolation, notexecution.
sessionoverlaps with other industry uses and with our own daemon-sidesession objects.
taskwas the prior name and carries a non-interactive connotation.This blocks the concrete shape of the run path (
min sandbox run claude-sessionvs
min task run …vs staying withmin run <task>), so it needs a decisionbefore the sweep in (1) can be specified. Worth doing as an explicit
terminology call rather than another thread.
Non-goals
decisions stand.
minimald/minvmdcommand surfaces.Acceptance criteria
<noun> <verb>convention (including singular/plural aliasing) iswritten down —
docs/reference/cli.mdor an ADR — not just implied by thecommand tree.
min's session surface matches the convention, with any retained top-levelaliases documented as deliberate ergonomic exceptions.
min completions install <shell>exists andscripts/install.shcalls itinstead of carrying its own copy.
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.
Related
(merged)
minimald/mincommand surface for Minimal One; this is a concrete child ofits "user-facing terminology audited and stabilized" outcome
min loginmissingfrom the CLI reference (same docs surface)