Getting Started

You need a local Git repository, a Shipper license and sign-in, and a supported coding agent CLI configured for Shipper. You can use Shipper through the CLI or the supported macOS desktop app; both entry points operate on the same local-store-backed workflow state, with optional GitHub projection.

The GitHub-backed posture is the recommended default path. For this path, add a GitHub origin remote and, for interactive use, authenticate with GitHub CLI:

gh auth login

For GitHub-backed 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 GitHub authentication fails on this path, start with the GitHub authentication troubleshooting guide.

CLI Path

Shipper is proprietary and is not published to npm. Licensed pilot users install it through the hosted macOS arm64 path.

1. Install for the first time

Install Node.js 22.12 or newer on a macOS arm64 machine, then visit the terms-gated Shipper downloads page. After you accept the terms, the page generates a first-install command containing a short-lived signed tarball URL and its SHA-256. Run that generated command. It needs no existing Shipper credential, which is why first-time users start at the downloads page instead of using the upgrade command below.

shipper auth login

See Licensing and authentication for how this sign-in is shared across Shipper surfaces and how offline access works.

3. Upgrade as a returning user

After signing in, returning users can resolve and install the current stable release with:

curl -fsSL https://shipper.baremetallabs.ai/install.sh | sh

This unparameterized upgrade command requires the stored credential created by shipper auth login. It is not a first-install command; new users must use the generated command from the downloads page.

4. Configure a repository

Then configure Shipper once per repository:

shipper setup --agent codex

shipper setup writes user-level per-repo settings with no working-tree footprint, records the selected agent, and fills an obvious dependency install command when detection is unambiguous. When issue projection is enabled on the GitHub-backed path, setup also ensures workflow labels exist in GitHub. Store-only repositories create no GitHub issue mirrors, labels, or issue comments for Shipper state. Setup is idempotent, so rerun it after upgrades or if a preflight check tells you the repo is not configured. Use shipper setup --assist when you want the richer agentic assistant while keeping the same user-level, no-footprint default. The assistant can discover bootstrap commands and explain CI, branch protection, and coding-agent configuration without writing repository files. Use shipper setup --repo for deterministic committed team configuration under .shipper/, or shipper setup --assist --repo when you want the assistant to write committed artifacts. On the PR-enabled GitHub-backed path, the assistant can also update workflows or agent config files, configure branch protections, and finalize those changes through a setup PR. 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:

shipper new "your idea"

Advance one stage at a time:

shipper next S#123

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

shipper ship S#123

shipper next reads the issue’s current local workflow stage 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. Use the issue identifiers reference for accepted local ID, explicit GitHub issue, and URL input forms.

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

No remote?

After seeing the workflow, you can use the same issue and stage commands without a git remote. The fully local recipe walks from repository setup through local packaging, locally held reviews, and a local merge. See Repository postures for the complete operating picture and the capabilities available in each posture.

Contributor and developer source checkout

Shipper contributors and developers can build the CLI from a Shipper source checkout instead of using the licensed-pilot installer. See the repository README’s “Contributor and developer source checkout” section. This is the development path, not the default licensed-user installation.

Desktop Path

Download the latest macOS arm64 artifact from the private repo’s GitHub Releases (authorized access), launch the app, and add or select a repository in owner/repo format. If the repo is not configured, run setup when the app prompts for it.

If a Shipper license alert appears, select Sign in. Desktop completes authentication in its in-app terminal and restores the selected repository’s board automatically without a relaunch.

See Licensing and authentication for details about the shared credential and desktop sign-in flow.

From there, use the pipeline board for issue intake, adoption, grooming, shipping, review, Rework, 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

Not signed in to Shipper. Run shipper auth login in a terminal, then relaunch.

See Licensing and authentication for details about the shared terminal sign-in.

If you want Claude Code, Codex, Grok Build, or OpenCode to call Shipper through MCP, run shipper setup for 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.