Skip to content

feat(cli): finish the <noun> <verb> command-surface sweep for min and mip #1005

Description

@norrietaylor

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 buildmin package build; min patched-pkgmin 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
    providermin 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
  • #972min login missing
    from the CLI reference (same docs surface)

Metadata

Metadata

Assignees

No one assigned

    Labels

    kind:featureA new feature or capability.oss-reviewBody exposes internal links or infra detail; review/scrub before the repo goes publicpriority:should-haveShould be done.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions