Licensing and authentication

A valid Shipper license is required for license-gated workflow operations. The gate applies to protected Shipper CLI stages, including those started by desktop or MCP; it does not mean that every local action on every Shipper surface checks a license.

Three separate kinds of authentication

Shipper uses three independent authentication concerns:

• Shipper account and license authentication establishes the entitlement used by protected Shipper workflows. Shipper owns and stores this credential.
• GitHub authentication authorizes repository operations. It is owned by the GitHub CLI (gh) or the documented GitHub token variables.
• Coding-agent authentication authorizes the selected coding-agent CLI with its provider. The agent and provider own that credential.

Signing in to one does not sign in to either of the others. For example, gh auth login does not sign you in to Shipper, and shipper auth login does not configure your coding agent.

Sign in from CLI or MCP

Run shipper auth login from an interactive terminal. The command opens a browser where you authorize the account and, on the account’s first login, accept the terms. If the terms change later, the browser presents the updated terms for acceptance. A successful login caches the returned entitlement locally.

Use shipper auth status to inspect the current license state. It is the authoritative source for the current OS user and machine’s grace-period end. Use shipper auth logout to remove the local Shipper credential. Signing out of Shipper does not affect GitHub or coding-agent credentials.

One sign-in across Shipper surfaces

Sign-in is completed once per OS user account on a machine. CLI, desktop, and MCP processes running under that account share its credential, cached entitlement, and revalidation state. As a brief multi-user consideration, a different OS user account on the same machine signs in separately and maintains its own cached entitlement and revalidation state.

For desktop, a signed-out, expired, or terms-outdated license alert includes a Sign in button. It runs the same browser authentication flow in the in-app terminal. After a successful sign-in, desktop automatically rechecks prerequisites, clears the alert, initializes the selected repository, and loads its pipeline issues without a relaunch. Cancelled or failed attempts remain visible in the terminal and can be retried. CLI and MCP users continue to run shipper auth login in an interactive terminal.

The resulting credential is still shared across CLI, desktop, and MCP processes for the OS user. Desktop and MCP protected workflow operations spawn license-gated CLI stages, so those stages inherit the CLI license gate; this does not make every desktop or MCP action individually gated. Signing in again cannot restore a revoked license; contact Bare Metal Labs support when the license guidance directs you to do so.

By intended v4 design, MCP server startup and local MCP tools are not themselves license-gated and require neither GitHub authentication nor GitHub reachability. GitHub-dependent MCP operations check GitHub access when invoked.

Revalidation and offline access

Shipper caches the entitlement locally and rechecks it automatically about once a day. The first protected command after the cached validation becomes stale triggers the recheck. That command can wait a few seconds at most for the bounded online validation to finish. Revalidation is coordinated, so concurrent commands do not pile up their own validation requests.

If Shipper cannot reach the licensing service, protected work continues for a limited grace period issued by the licensing server, and Shipper warns you during that window. A temporarily unreachable licensing service does not revoke access while the account and machine remain within the grace window. After the grace period ends, protected commands are blocked until an online revalidation succeeds.

Keep the local system clock accurate. Freshness and grace decisions compare local time with server-issued validation and grace timestamps. Because the licensing server controls the grace window, use shipper auth status for its authoritative end on the current OS user and machine.