Skip to content

CLI Reference

New here? docs/concepts.md explains how WorkItem / Spec / Plan / Task / worktrees / agents relate, with diagrams.

All task-scoped commands (status, phase, test, journal, view …, etc.) resolve their target task in this priority order:

  1. --task <slug> flag — explicit, highest priority.
  2. MSHIP_TASK env var — scope a whole shell session to one task.
  3. cwd — if your shell is inside a task's worktree, that task is the default.

With 0 active tasks the command errors with "no active task". With exactly 1 active task and no anchor, the command targets that task. With 2+ active tasks and no anchor you'll get an "Ambiguous" error listing the active slugs — fix by anchoring via any of the three mechanisms above.

Lifecycle

mship init [--detect | --name N --repo PATH:TYPE]   # scaffold mothership.yaml
mship init --install-hooks                          # (re)install Git hooks plus lifecycle integrations:
                                                    # Claude at workspace .claude/settings.json;
                                                    # Codex and OMP in every configured Git root:
                                                    # .codex/hooks.json (review via Codex /hooks)
                                                    # .omp/extensions/mship.ts
                                                    # Commit project artifacts so worktrees inherit them.
                                                    # Entire PreToolUse edit-guard bypass: MSHIP_ALLOW_MAIN_EDIT=1.
mship spawn "description" (--work-item <id> | --hotfix) [--repos a,b] [--skip-setup] [--bypass-reconcile]
                                                    # --work-item <id> required (create via `mship item new`);
                                                    # bypass the gate with --hotfix. Also: --depends-on, --base, --slug.
mship switch <repo>                                 # cross-repo context switch
mship phase plan|dev|review|run [-f]                # transition with soft-gate warnings
mship block "reason" | mship unblock
mship test [--all] [--repos|--tag] [--no-diff]
mship journal [-]                                   # read task log; pass message to append
mship journal "msg" [--action X] [--open Y] [--repo R] [--test-state pass|fail|mixed]
mship journal --show-open                           # list open questions
mship finish [--body-file PATH | --body TEXT] [--base B] [--base-map a=B,b=B] [--push-only] [--handoff] [--force-audit] [--bypass-reconcile] [--force]
mship close [--yes] [--abandon] [--force] [--skip-pr-check] [--bypass-reconcile]
mship commit "message" [--task <slug>]              # commit staged changes; push new or existing commits if finished
mship depends add|remove|list                       # manage task-to-task dependency edges (#104)

For a finished task with a recorded PR, mship commit also pushes already-made commits when the index is clean and the branch is ahead of its upstream. It does not create another commit in that case; the message is used only for staged changes. Repos with nothing to push are skipped successfully. Missing upstreams and failed pushes are reported as errors, so you can resolve them and retry the same command. Before finish, this command commits staged changes but never pushes.

mship init --install-hooks writes the project-local Codex hook files, but it does not enable Codex features or trust the project. If setup reports the hook capability as disabled or unavailable, run codex features enable codex_hooks. Then open /hooks in Codex to review and trust the project hooks. Trust remains a manual action even when the capability is already enabled.

mship doctor reports these boundaries separately: whether the project hook artifact is valid, whether the Codex hook feature capability is enabled, and whether manual project trust remains unresolved. A current registration is therefore configured but untrusted, not reported as fully active.

Codex edit failures also have distinct signatures. A Mothership edit-gate denial exits with status 2 and starts stderr with mship edit gate rejected:; MSHIP_BYPASS_GATE=1 bypasses only the WorkItem/spec gate, while MSHIP_ALLOW_MAIN_EDIT=1 currently exits before the event is parsed and therefore bypasses the entire PreToolUse edit guard, including WorkItem/spec checks. Neither override affects sandbox bootstrap. By contrast, bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted means the Codex filesystem sandbox failed before the requested edit ran. On Ubuntu hosts with restricted unprivileged user namespaces, ask the host operator to install the intended profile if needed. It may already be at /etc/apparmor.d/bwrap-userns-restrict; only if it is absent should the operator locate a distribution-provided copy (often /usr/share/apparmor/extra-profiles/bwrap-userns-restrict) and install or copy it per that distribution's guidance. This diagnostic cannot detect whether another AppArmor profile already attaches /usr/bin/bwrap: inspect the host policy configuration and reconcile any collision before loading the intended profile with sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict. Restart Codex and retry the original edit tool. Verify recovery with an add-update-delete cycle; do not substitute a shell, Python, or other unapproved file writer.

mship doctor and mship init --install-hooks diagnose this Ubuntu prerequisite from the user-namespace restriction, installed profile, and current confinement state. They deliberately do not launch nested bwrap: inside a working Codex sandbox that nested launch can fail normally. When the profile exists but its loaded state cannot be confirmed from the sandbox, the commands warn and direct the operator to verify it from the host.

Entry point — spawn vs. spec dispatch: mship spawn starts an ad-hoc task directly, but for spec-driven work you don't call it first. mship spec dispatch <id> (see Work items & specs below) is the entry point: it binds an approved spec and spawns its own task. Running spawn and then spec dispatch against the same spec double-creates tasks (#296). Rule of thumb: have an approved spec → spec dispatch; ad-hoc chore/bug → spawn.

mship close closes task state without deleting worktrees, branches, or hub files. This also applies to passive detached dependencies, merge auto-close, --abandon, and --force; force bypasses lifecycle checks, not data retention. Before active state is removed, a private, durable Task snapshot is saved under .mothership/retained-worktrees/. If retention fails, active state remains. mship worktrees lists active tasks and recovery records, including original paths. Retained worktrees remain managed for audit purposes and do not block new tasks.

Cleanup is separate: inspect mship prune, stop all agents, editors and Git processes using the listed paths, then run mship prune --force --writers-stopped. Here --force executes cleanup; it never passes --force to Git. Cleanup refuses tracked changes, untracked or ignored files, unregistered paths, and uncertain Git state. Git refusal leaves the directory intact; there is no recursive deletion fallback. Unexpected hub files and branches remain. Review and preserve any reported files yourself before retrying.

Before deleting a clean worktree, its HEAD is pinned in the owning repository under refs/mship/recovery/<SHA-256-of-resolved-path>/<commit>. Cleanup reports the ref. To recover committed content, run in that repository:

git for-each-ref --format='%(refname) %(objectname)' refs/mship/recovery/
git worktree add --detach /new/recovery/path <reported-recovery-ref>

Recovery records and refs remain after cleanup. Refs protect committed content, not uncommitted files or commits created after the cleanup snapshot. The --writers-stopped flag is an operator acknowledgement, not an exclusive lock: if writers cannot be stopped, leave the worktree retained.

Missing worktree paths are also snapshotted before stale task mappings are removed. Cleanup does not broadly prune Git registrations: a missing path may be offline or moved rather than disposable. After locating a moved worktree, use git worktree repair /moved/path from its owning repository to repair registration.

Setup & admin

mship bootstrap [--repos a,b] [--token TOK]         # clone missing workspace members (fresh clone -> full workspace)
mship skill install|list [--only claude,codex,gemini,omp,pi] [--force] [-y]  # pi is the canonical alias for omp
mship gh preflight                                  # fail-fast check that GitHub auth covers the workspace repos
mship bind refresh                                  # re-sync bind_files + symlink_dirs from source repos into worktrees
mship layout init|launch                            # write / launch the mothership zellij layout

Codex and OMP/Pi use the same user-level .agents/skills/mothership link to the bundled skills; installing both does not create a second copy. Install safe-skips foreign links, files, and directories unless --force is explicit. mship doctor reports OMP skill discovery independently from project lifecycle extension compatibility and recommends mship skill install --only omp (plus --force for foreign content) when repair is needed.

mship relay manages reverse-tunnel client keys and relay-owner state (for mship serve --relay, see relay-hosting.md). Every relay-owner command uses the same explicit <store> as enroll-server:

mship relay setup                                             # generate the client relay SSH key
mship relay enroll                                            # request relay access from a new device
mship relay enroll-server --store-dir <store> ...             # run the public endpoint on the relay host
mship relay requests --store-dir <store>                      # list pending enrollment requests
mship relay approve <id> --store-dir <store> --pubkeys-dir <pubkeys>
mship relay deny <id> --store-dir <store>
mship relay fleet-token --label phone --relay-domain <relay> --store-dir <store>
mship relay hosts --store-dir <store>                         # list the daemon host directory

Work items & specs

A work item is the durable unit of intent (feature/bug/chore/question) that a task implements; a spec is its approved design and a plan is its implementation breakdown. Feature work items gate phase dev/finish on BOTH an approved linked spec AND a linked/discovered implementation plan (bugs and chores need neither).

mship item new "title" --kind feature|bug|chore|question   # create a work item
mship item list [--all]                             # list work items (--all includes archived)
mship item show <id>                                # detail incl. linked spec/tasks
mship item phase <id> <phase>                       # move the item through its lifecycle
mship item link-spec|link-task|link-url <id> <ref>  # attach a spec, task, or URL
mship item link-plan <id> <path>                    # attach an implementation plan doc (feature plan-gate)
mship item archive|unarchive <id>                   # soft-hide / restore

mship state status                                  # inspect legacy/SQLite backend and schema revision
mship state migrate                                 # explicit legacy cutover or known SQLite schema upgrade
mship state migrate --preview                       # read-only ownership plan, including all conflicts
mship state migrate --resolve-owners owners.json     # explicit resolutions for ambiguous legacy task links
mship state export --format json|yaml               # deterministic Task/WorkItem records on stdout

mship spec new --title "title"                      # create a spec (lands in needs_review)
mship spec draft <id> [--from-text "..."]           # emit an authoring prompt for an agent
mship spec apply <id> --from-json <file>            # populate the spec from JSON
mship spec review <id> | mship spec show <id>       # read a spec
mship spec verdict <id> <criterion> <verdict>       # record a per-criterion review verdict
mship spec request-changes <id> --reason "..."      # send a spec back with a reason
mship spec approve <id>                             # mark approved (unblocks dev/finish)
mship spec dispatch <id> [--task <slug>]            # bind an approved spec to a task + emit handoff
mship spec list                                     # list specs

Specs live at <workspace>/specs/<date>-<id>.md. Lifecycle: new → draft → apply → review → approve → dispatch.

Plans are first-class too. A feature work item can't enter dev or finish without a valid implementation plan — either linked via mship item link-plan or discovered at <docs_dir>/plans/<date>-<slug>.md (what the writing-plans skill produces), and containing at least one task block. Bypass with mship phase dev --bypass-plan-gate or mship finish --hotfix. Build dispatch is plan-driven: once a plan is linked, mship dispatch --task <slug> --plan-task N mints the implementer prompt from the plan (no --plan needed), and mship spec dispatch points the build at the plan's tasks instead of re-deriving from the spec.

Messaging & serve

mship serve exposes a JSON API over the spec + task model (reads plus review/approve writes) — the backend for the Ground Control app and remote agents. The mailbox is a durable store-and-forward channel between a phone and an agent.

mship serve [--relay] [--port N]                    # run the JSON API over the spec/task model (+ mailbox)
mship inbox wait [--since TS] [--timeout S]         # block until a new human message arrives (JSON)
mship reply <thread_id> "text"                      # reply to a mailbox thread
mship ask <thread_id> "question" --option A --option B  # post a decision (>=2 tappable options; --recommend/--multi/--no-free-text)
mship messages <thread_id>                          # print a mailbox thread's conversation in order
mship pair                                          # print a pairing deep-link + QR to connect the Ground Control app

Inspection

mship status                                        # task, phase, branch, drift, last log, finished warning
mship context                                       # one-shot agent-readable JSON snapshot of workspace state
mship dispatch --task <slug> -i "<instruction>"     # emit self-contained subagent prompt to stdout (default: implementer framing — report back, no PR)
mship dispatch --task <slug> --mode standalone -i "<instruction>"  # standalone framing — subagent finishes and opens its own PR
mship audit [--repos r] [--json]
mship reconcile [--json] [--ignore SLUG] [--clear-ignores] [--refresh]
mship reconcile --adopt-merged SLUG                  # verify merged PRs and recover missing task PR URLs/finish time; no teardown
mship pr                                            # PR state for every active task with recorded PR URLs
mship debug hypothesis "..." | rule-out "..." | resolved  # structured debugging journal entries (#30)
mship view status|journal|diff|spec [--watch]
mship view spec --web                               # serve rendered spec on localhost
mship graph
mship worktrees
mship doctor [--no-network] [--remote[=role] --task TASK --repo REPO] # local health or read-only selected-host tools report
mship net status [--no-network]                     # connectivity topology: serve, relay, run hosts, gh auth, egress
mship ui [--no-browser] [--host h] [--port p]       # open the serve-host console (opens a browser, else prints a copyable link)

The console has three pages: /ui (connectivity topology, worst-first, self-refreshing), /ui/doctor (the full mship doctor report), and /ui/pair (a pairing QR — on its own page because a pair link embeds the serve token, so that page displays a credential).

The console lives at /ui on the serve host. When the serve runs with auth (any relay setup does), a browser cannot send the bearer header from its address bar — so visit it once via mship ui, which builds /ui?token=<serve token>; the console exchanges that for a short-lived cookie and cleans the URL. GET /net/topology continues to accept only the Authorization header.

Maintenance

mship sync [--repos r]                              # fast-forward behind-only clean repos
mship prune [--force --writers-stopped]              # inspect; explicitly clean quiescent worktrees
mship export [--redacted] [--format dir|zip]        # bundle a task's journal/plan/spec/state/diffs (opt-in secret redaction)
mship state status                                  # read-only storage backend/revision inspection
mship state migrate                                 # validated legacy cutover or known SQLite schema upgrade
mship state migrate --preview                       # inspect all ownership corrections/conflicts without writes
mship state migrate --resolve-owners owners.json     # apply a JSON task-slug -> WorkItem-ID resolution map
mship state export --format json|yaml               # full Task/WorkItem data only

Workspace state storage

New workspaces initialize .mothership/mothership.db for Task and WorkItem state. Existing state.yaml and workitems/*.json files remain authoritative legacy inputs until an explicit migration; mship never dual-writes them with SQLite.

mship state status is read-only. Its structured output contains backend, database_path, current_revision, head_revision, and migration_required, so operators can check compatibility before maintenance.

Stop the per-user daemon before running mship state migrate. For legacy Task/WorkItem files, migration takes exclusive state locks, validates every record, and copies the live inputs to .mothership/backups/<UTC timestamp>/. It builds and verifies a candidate database before atomically activating mothership.db; a failure leaves the legacy files live and can be retried. Successful legacy paths are retained beside the database with a .migrated-<UTC timestamp> suffix.

Before legacy cutover, mship state migrate --preview lists every proposed ownership resolution, changed WorkItem task-link list, missing Task owner correction, and unresolved conflict. Use mship --json state migrate --preview for structured output. Preview is read-only and returns a nonzero exit status if conflicts remain; apply recomputes the plan while holding the migration and legacy writer locks.

A current Task's valid explicit work_item_id wins over competing WorkItem backreferences. Only stale backreferences and repeated links are removed; no WorkItem is deleted or merged, and titles, timestamps, spec/plan links, threads, archive flags, and unrelated associations are preserved. If a current Task has no work_item_id, a sole claimant or explicit operator choice fills that missing forward link. This correction is shown in the preview and recorded in the audit report; an existing explicit owner is never overwritten. An explicit owner ID that references a missing WorkItem remains a conflict.

For removed tasks with competing claimants, automatic resolution requires agreement among explicit owners in retained application-native Task snapshots: .mothership/backups/*/state.yaml and .mothership/state.yaml.migrated-*. Snapshot age, WorkItem order, titles, and shared spec IDs do not break ties. Missing, unreadable, or contradictory evidence requires an operator decision; agent transcripts and session-history tools are not migration dependencies.

Supply ambiguous choices as a JSON object, for example {"closed-task": "wi-canonical"}, using --resolve-owners owners.json. Preview that map first with mship state migrate --preview --resolve-owners owners.json, then apply without --preview. Each choice must name an existing claimant; it cannot override a current Task's valid explicit owner. Unknown task slugs, missing owners, duplicate JSON keys, and invalid values are rejected.

The backup retains the exact original input bytes and any historical snapshots used as evidence. Its migration-report.json records ownership decisions, removed links, Task owner before/after values, rules, and input/evidence fingerprints; the verified database stores the plan and the report path/hash. Corrections exist only in the candidate database until activation. Repeating a completed migration with the same recorded owner choices is also a no-op; a different map cannot rewrite existing SQLite ownership.

For an existing SQLite database at a known older packaged revision, the same command reserves the writer, creates a consistent owner-private backup, and reports its location. It applies the packaged upgrade transactionally and verifies the resulting revision, foreign keys, and preserved Task/WorkItem data before committing. A failed upgrade rolls back; unknown or future revisions are not guessed or overwritten. Repeating a successful migration is a no-op. Preview enforces the same revision compatibility rules as apply: unversioned, unknown, and future SQLite revisions are rejected without modifying state. SQLite preview refuses while WAL/shared-memory sidecars exist rather than modifying them or reading stale data. Close active database users and let SQLite checkpoint before retrying.

The cutover has no dual-write period. Once mothership.db is active, the SQLite database is authoritative and older Mothership binaries that only write state.yaml or WorkItem JSON are unsupported. A database at an unknown or incompatible Alembic revision is refused with the current and required revisions rather than being changed implicitly.

mship state export --format json and --format yaml emit the same stable, sorted Task and WorkItem payload, including archived WorkItems. The export does not include app-run metadata or traverse private target bindings, mailbox messages, secrets, specs, journals, or artifact bytes. This is not a full database backup. It is distinct from mship export, which builds a task review bundle.

Long-running services

mship run [--repos a,b] [--tag t] [--remote[=role]] # start services per dependency tier
mship logs <service>                                # tail logs for a service
mship run-host add|list|remove|pair-relay|migrate # private direct or relay run-host identities
mship build [--all] [--repos a,b] [--tag t] [--remote[=role]]  # `task build` across repos in dependency order
mship capture [--repo R] [--platform P] [--kind image|layout|all] [--out DIR] [--remote[=role]]
                                                    # screenshot + layout of the running UI into files;
                                                    # task-aware but not required (ad-hoc against a repo's main checkout)

mship run, mship build, and mship capture keep their existing --remote[=role] entry points: bare --remote auto-resolves the repo's run_host (or the sole configured run_hosts entry), while --remote=<role> picks one explicitly.

run-host add has two mutually exclusive forms. Direct setup retains --url/--token or the direct --pair-link. Relay setup uses only --relay, --host-id, and --workspace-id after the coordinator has consumed the relay owner's existing account link using the echo-hidden mship run-host pair-relay prompt. run-host migrate NAME --relay ... previews that selected directory identity until --apply writes a private backup and replaces the named direct mapping. No relay command accepts, prints, or stores a fleet credential, refresh credential, bearer, standing token, or mutable public relay URL. For a repository that declares host_tools, inspect only its selected remote worktree with mship doctor --remote[=role] --task TASK --repo REPO. Provision that exact reviewed mise declaration only with mship bootstrap --host-tools --remote[=role] --task TASK --repo REPO. Neither command probes the caller's toolchain, runs application setup/tasks, or accepts SDK licenses. Ordinary doctor and bootstrap retain their existing local workspace behavior.

Repositories with configured run_profiles support task-bound launches through mship run --profile NAME, optionally constrained by --host NAME and --target ALIAS. Packaged Flutter, Android, iOS, browser, and PlatformIO backends are opt-in through configuration and require prepared host prerequisites.

capture and logs can observe an existing acknowledged profile run using --run-id, or narrow recorded runs with --profile, --host, and --target. Recorded-run selectors require a resolvable active task (--task, MSHIP_TASK, or cwd); they do not launch a replacement session. Ordinary service log tailing remains available without a task when no recorded-run selector is supplied.

mship run --task feature-a --repos app --profile android-usb --host lab-android --target pixel-8
mship capture --task feature-a --repo app --run-id <run-id>
mship logs app --task feature-a --run-id <run-id>

The shared typed runner and POST /exec/tool remain internal adapter APIs, not a separate public CLI command. See remote-run.md for profile configuration, relay credential handling, source/binary provenance, and platform-specific verification limits. Command availability alone does not establish hardware, binary, or device readiness.

mship finish

PR body

mship finish rejects empty PR bodies. Two ways to provide one:

mship finish --body-file /tmp/pr-body.md            # read from file
echo "..." | mship finish --body-file -             # read from stdin
mship finish --body "inline text"                   # inline (also supports `-` for stdin)

A TTY guard on both - forms errors fast if stdin is an interactive terminal instead of hanging.

PR base branch

Each repo's PR can target a non-default base. Resolution order (most-specific wins):

  • --base <branch> — global override for all repos.
  • --base-map cli=main,api=release/x — per-repo overrides.
  • base_branch in the repo's mothership.yaml entry.
  • Remote default branch.

mship finish verifies every resolved base exists on origin before any push.

--force vs normal re-finish

mship finish is idempotent: a second run after finished_at is stamped is a no-op. To push additional commits to the existing PRs (e.g., reviewer feedback), use mship finish --force. It pushes, updates finished_at, writes a re-finished journal entry, and does NOT create a new PR or modify the existing body. Edit the body separately via gh pr edit <url> --body-file <path>.

Drift audit & sync

Issue codes

  • Errors (block spawn/finish): path_missing, not_a_git_repo, fetch_failed, detached_head, unexpected_branch, dirty_worktree, no_upstream, behind_remote, diverged, extra_worktrees.
  • Warnings (don't block): dirty_untracked (untracked files only).
  • Info-only: ahead_remote.

Per-repo policy

repos:
  schemas:
    path: ../schemas
    expected_branch: marshal-refactor
    allow_dirty: false
    allow_extra_worktrees: false

Workspace policy

audit:
  block_spawn: true
  block_finish: true

Commands

  • mship audit [--repos r1,r2] [--json] — exit 1 on any error-severity drift.
  • mship sync [--repos r1,r2] — fast-forwards behind-only clean repos.
  • mship spawn --force-audit / mship finish --force-audit — bypass with a line logged to the task log.

Live views

mship view provides read-only TUIs designed for tmux/zellij panes. All views support --watch and --interval N.

  • mship view status [--task <slug>] [--watch] — all tasks stacked by default; --task narrows to one.
  • mship view journal [--task <slug>] [--watch] — tail the task's journal.
  • mship view diff [--task <slug>] [--watch] — per-worktree git diff.
  • mship view spec [name-or-path] [--task <slug>] [--watch] [--web] — cross-task spec index picker by default.

Keys: q quit, j/k or arrows to scroll, PgUp/PgDn, Home/End, r force refresh.