shipper setup

Usage: shipper setup [options] [words…]

Configure Shipper for the current repository

Arguments

Argument	Required	Description	Choices
[words…]	no	-	-

Flags

Long	Short	Value	Default	Description	Choices
—repo	-	-	-	write committed .shipper/ configuration instead of user-level settings	-
—assist	-	-	-	run the agentic setup assistant	-
—agent	-		-	agent to use: claude, codex, copilot, grok, or opencode	claude, codex, copilot, grok, opencode
—autocommit	-	-	-	stage and commit .shipper/ after writing files (requires —repo)	-
—push	-	-	-	push the setup commit to the remote (requires —repo —autocommit)	-
—mode	-		default	assistant execution mode: headless, interactive, or default	headless, interactive, default
—model	-		-	model to use for the assistant agent CLI	-
—reasoning-effort	-		-	reasoning effort to pass to the assistant agent CLI	-
—disable-mcp	-	-	-	disable MCP server loading for the assistant run	-
—enable-mcp	-	-	-	enable MCP server loading for the assistant run	-

Examples

Write user-level settings for this repository without touching the working tree.

shipper setup --agent codex

Write committed team configuration under .shipper/.

shipper setup --repo

Explicitly pin the shared repository coding agent.

shipper settings set commands.default.agent codex --repo

Run the assistant while writing user-level settings and no repo artifacts.

shipper setup --assist

Run committed assisted setup; GitHub-backed repositories use a setup PR, while fully local repositories leave changes for review.

shipper setup --assist --repo

Exit Codes

Code	When
0	Repository validation and configuration writes succeed; GitHub-backed flows also complete their authentication, policy, and label work.
1	Local validation, configuration writes, assisted agent execution, linked GitHub work, or assisted setup finalization fails.

Constraints

Design, Plan, Implement, Review, Rework, and Ready name next work. Designed simple issues next Implement; complex or undecided issues next Plan. Packaged work next Review in either PR mode. Ready means ready for final integration, not shipped. New stays separate; held and failed are excluded (hold wins), while blocked, locked, paused, and running retain membership. CLI/MCP retain six next-step groups; desktop has five columns, with Implement combining Implement and Rework for the same population and attention exclusions. Current nextStep and nextStepPipeline are additive; completed-stage pipeline fields, labels, filters, commands, reset arguments, and historical records retain their meanings. Maintained label descriptions automatically refresh during next normal setup or maintenance, without separate initialization; successful cache skips repeats and force refresh reads again. Read-only status makes no label writes.
With no location flag, setup writes user-level per-repo settings and never prompts for location.
User-level deterministic and assisted setup support committed repositories with no GitHub origin or with a non-GitHub origin; that local-only path uses an identity-keyed personal settings file and bypasses GitHub authentication, remote, policy, and label prerequisites.
A repository with no commits cannot be assigned a stable repository identity; local repository-target and user-target setup instruct the operator to make an initial commit and write nothing.
If local-only assisted setup creates an explicitly opted-in .shipper/hooks/worktree-setup hook, setup succeeds with the hook left in the working tree for manual review and commit rather than setup-PR finalization.
—repo writes committed .shipper/ configuration in the repository working tree.
Repository-target setup supports a GitHub-backed repository or a committed repository whose resolved transport policy is none; an origin remote on another host is unsupported.
Fully local —repo setup uses the stable local repository identity, requires no GitHub CLI or authentication, performs no GitHub repository lookup, and provisions no workflow labels.
Fully local setup writes the same committed artifact paths and CLI freshness fingerprint as GitHub-backed setup, plus explicit transport: "none"; it leaves pullRequests, reviewDelivery, and every other unexpressed policy or default omitted.
An explicit no-transport posture continues to win if an origin remote is added later. A no-transport repository that explicitly requests mirrorMode: "mirror-on" is rejected with policy-resolution guidance.
—assist runs the agentic setup assistant; by default it writes user-level settings and gives guidance without repository footprint.
For GitHub-backed repositories, —assist —repo remains the explicit opt-in for committed assisted setup artifacts and uses setup-PR finalization.
For fully local repositories, —assist —repo performs no GitHub inspection, branch creation, commit, pull request, finalization, or adoption; it reports changed paths and local posture, then leaves the working tree for operator review and commit.
Positional words, —mode, —model, —reasoning-effort, —disable-mcp, and —enable-mcp require —assist.
—autocommit and —push require —repo; —push also requires —autocommit.
Fully local deterministic —autocommit stages and commits the standard artifacts locally. —push is refused before install detection or writes because no remote transport exists.
Deprecated compatibility: shipper init is hidden from help, aliases shipper setup —repo, emits a deprecation warning, and will be removed in a future release.
For assisted setup, —disable-mcp and —enable-mcp are mutually exclusive.
Headless mode is not supported for shipper setup —assist; run assisted setup interactively or remove “commands.setup.mode”: “headless” / “commands.default.mode”: “headless” from .shipper/settings.json.
GitHub authentication, repository lookup, workflow labels, and setup-PR finalization apply only to GitHub-backed setup.
Troubleshooting: GitHub authentication problems
Troubleshooting: missing or duplicate workflow labels
Troubleshooting: worktree creation and install command failures
Troubleshooting: MCP tool loading issues
Assisted setup (--assist) is the only setup path that qualifies for macOS idle-sleep protection; bare setup and deprecated init do not. See Keep the Mac awake during active work.