sparkles:dman — CLI Surface

The concrete dman v1 command tree — the scriptable interface, defined with the same command schema (D5/D6) dman uses to invoke git. Every operation is available non-interactively; bare dman (on a TTY) launches the TUI shell. Commands delegate to the VCS backend and repo catalog.

The command tree

The root carries global options that reach every leaf; subcommands are the noun-verb tree:

@Command("dman")
struct Dman {
    @Option("repo")      string repo;        // PATH | URL; default = CWD walk-up
    @Option("config")    string configPath;
    @Option("json")      bool   json;        // emit wired-JSON instead of tables
    @Option("v|verbose") bool   verbose;
    @Option("no-color")  bool   noColor;

    @Subcommands SumType!(Repo, Branch, Worktree, Status, Tui) command;
}

@Command("branch") struct Branch {
    @Subcommands SumType!(List, Show, Delete, Create, Switch) command;

    @Command("delete") struct Delete {
        @Option("force")   bool     force;      // allow unmerged
        @Option("dry-run") bool     dryRun;
        @Option("yes")     bool     yes;        // no confirm (CI)
        @Argument("name")  string[] names;      // multi-select
    }
    // List: @Option filter/sort/search flags; Show/Create/Switch analogous
}

Commands → operations

Command	Does	Backend call
dman repo scan [--root DIR]… [--depth N]	discover + catalog repos	catalog scan
dman repo list [--tag T] | add | remove | show	manage the catalog	catalog
dman repo tag add|remove <tag>	manage user tags	catalog
dman workspace list | show | create | members | delete	multi-repo groups	Workspaces
dman branch list [--filter --sort --search]	classified branch list	VcsRepo.branches
dman branch show NAME	one branch's detail	VcsRepo.branches
dman branch delete NAME… [--force --dry-run --yes]	delete branches	VcsRepo.deleteBranch
dman branch create | switch	create / switch	(git via schema)
dman worktree list | add | remove | prune	worktree ops	VcsRepo.*Worktree*
dman worktree enter NAME	cd in + record context	D13
dman worktree exec NAME -- CMD…	run in worktree (exit code)	D13
dman status	repo status	VcsRepo.status
dman (TTY) or dman tui	interactive UI	TUI shell

Scripting & machine output

• --json on any read command emits wired-JSON of the typed result (BranchInfo[], WorktreeInfo[], RepoRef[]) — the same structs the TUI renders, straight to a pipe. The struct field-names are the JSON keys (D6).
• Mutations support --dry-run (show what would happen, write to the action log) and --yes (skip confirmation). The non-interactive path is genuinely prompt-free — no hidden prompt may block a --yes run — so branch/worktree cleanup scripts work unattended in CI.
• Exit codes are structured and actionable: distinct codes for selection failures (a reserved code meaning "selection required"), protected-branch refusals, and tool errors.

Interactive vs non-interactive

Bare dman on a TTY opens the TUI; a non-TTY invocation or an explicit subcommand runs the scriptable path. Both drive the same VcsRepo + catalog + command schemas — the TUI is a second front-end over the identical core, not a fork.

Git-compatible passthrough

Because the command schema parses and renders, dman can forward git-style arguments to real git (parseKnownCli collects unrecognized flags), so a thin dman git … wrapper — or accepting familiar git flags on dman's own verbs — costs no extra code. See Command schema.

Maintenance & diagnostics

• Cache admin — a stats-and-exit flag prints catalog/cache stats without launching the UI; a force-refresh flag bypasses cache reads but still writes; a TTL override (0 = disable reads); plus dev recipes to show / open / clear the store — the SQLite catalog is inspectable, not a black box.
• Benchmark & perf — hidden diagnostic flags (force-sequential; fetch-then-exit with timing before the UI) plus a committed benchmark harness make scan/enrich regressions measurable.

Backend dispatch & jj-only verbs (P3)

The command tree above is backend-neutral: dman branch/worktree/status dispatch to the per-repo backend the catalog recorded (git or jj), with an optional --backend override. When the jj backend lands (D8, Designing for jj) it adds capability-gated verbs that have no git counterpart — dman op log / dman undo (real operation-log undo), dman worktree update-stale, and bookmark track/untrack + delete-vs-forget — hidden or erroring on git repos. On jj, worktree maps to jj workspace and branch to bookmarks; dman's --dry-run action log gains genuine one-command undo behind it.