CLI Reference¶
New here?
docs/concepts.mdexplains 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:
--task <slug>flag — explicit, highest priority.MSHIP_TASKenv var — scope a whole shell session to one task.- 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 spawnstarts 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. Runningspawnand thenspec dispatchagainst 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_branchin the repo'smothership.yamlentry.- 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;--tasknarrows 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.