Skip to content
Shipper

Getting Started

You need a Git repository with a GitHub remote, an authenticated GitHub CLI, and a supported coding agent CLI configured for Shipper. You can use Shipper through the npm CLI or the supported macOS desktop app; both entry points operate on the same GitHub-backed workflow state.

For interactive use, authenticate with GitHub CLI:

Terminal window
gh auth login

For containers or CI, export GH_TOKEN or GITHUB_TOKEN in the environment where Shipper runs. See the Containers reference for the token and git credential helper path. For the full list of supported environment variables, see Environment variables. If authentication fails, start with the GitHub authentication troubleshooting guide.

CLI Path

Section titled “CLI Path”

Install the CLI:

Terminal window
npm install -g @baremetallabs-ai/shipper-cli

Initialize Shipper once per repository:

Terminal window
shipper init

shipper init creates or updates .shipper/, ensures the workflow labels exist in GitHub, and checks the required local tooling. It is idempotent, so rerun it after upgrades or if a preflight check tells you the repo is not initialized. For initialization or workflow-label recovery, see missing or duplicate workflow labels; for upgrade drift, see CLI version drift and version mismatch.

Create a first issue from a rough request:

Terminal window
shipper new "your idea"

Advance one stage at a time:

Terminal window
shipper next <issue>

Or ask Shipper to run the remaining workflow for one issue:

Terminal window
shipper ship <issue>

shipper next reads the issue’s current workflow label and dispatches the matching stage command. shipper ship keeps dispatching until the issue reaches the next terminal point, including orderly rollback and resume behavior when an agent returns a reject verdict.

These commands are the CLI equivalents of the same issue lifecycle shown in the desktop app.

Desktop Path

Section titled “Desktop Path”

Download the latest macOS arm64 artifact from GitHub Releases, launch the app, and add or select a repository in owner/repo format. If the repo is not initialized, run setup/init when the app prompts for it.

From there, use the pipeline board for issue intake, adoption, grooming, shipping, review, remediation, unblock/reset/unlock operations, priority changes, auto-ship, and auto-merge. The Desktop guide has the full first-run walkthrough and current distribution constraints.

MCP Client Path

Section titled “MCP Client Path”

If you want Claude Code, Codex, or OpenCode to call Shipper through MCP, initialize the target repository first and then follow MCP setup. That guide covers building the private workspace MCP server from a Shipper checkout, configuring the client, setting SHIPPER_REPO_DIR, and verifying that Shipper tools resolve the intended repository.