Targets

A Target is one CLI, MCP server, or SDK that Typeship generates and maintains from your API Spec. Give it a Delivery when you want Typeship to send its output to a repository or hosted endpoint.

Start from the consumer

The cli Target includes everything it needs to call your API. It is the initial selection for a new Project and does not require an SDK Target.

Common combinations

Public developer platform. Generate a CLI for people and automation, MCP for agent clients, and SDKs for the application languages you support. Each can publish from a dedicated repository or an independent directory in one monorepo.

Internal API. Start with a CLI and hosted MCP when people mostly use the API from terminals and agents. Add an SDK only when an application needs a library dependency.

One language, two audiences. Create two Targets using the same generator when public and internal consumers need different package names, configuration, repositories, or release schedules. They remain separate tgt_* resources even though both use typescript-sdk.

One package in a monorepo. Create one Target with one repository Delivery and set its directory. A Target owns that generated tree. Adjacent Targets need non-overlapping directories.

Everything in one monorepo. Keep the API source, application, CLI, MCP server, and SDKs together. Give every generated Target a sibling directory; one root workflow publishes only the Target manifest changed by a merge. See Publish from a monorepo.

Target or Delivery?

Create another Target when the generated product needs its own identity or release decision. Add or change a Delivery when that Target needs a destination.

Repository Deliveries use GitHub. The MCP Target also receives a hosted MCP Delivery by default.

typeship targets create --project-id prj_... \
  --name "Parcel Internal TypeScript SDK" \
  --type typescript_sdk \
  --deliveries '[{"type":"repository","repository":{"provider":"github","identifier":"parcel/internal-typescript","package_name":"@parcel/internal"}}]'

type and spec_id cannot change after creation. Configuration, Deliveries, status, release channel, and the next proposed version can.

Configuration

Each Target inherits Project.config and may store overrides. GraphQL settings remain on the Spec.

Authentication has one narrow Target-level choice. Define OAuth applications on the Project, then select one with Target.config.auth.oauth_application. A CLI and local MCP Target can share a desktop application; another Target can select a different one. OAuth server settings and identity verification remain Project-owned.

mcp.access is separate from API sign-in. A self-hosted MCP Target may override it when that deployment has its own issuer or resource URL.

Update a Target

PATCH /targets/{target_id} requires at least one field. Omit a field to keep its stored value. type is immutable, and a Target always uses its Project's Spec. Change Deliveries through the Delivery operations.

Except for config, these fields reject null. Select the next package version on the Target's open Draft, named by draft_id, with PATCH /drafts/{draft_id} and version_next. Target updates accept an optional If-Match header with the Target's ETag; a stale ETag returns 412 precondition_failed. Retrieve, reconcile, and retry. Without it, concurrent updates preserve omitted fields, and updates to the same field replace it in save order. A supplied nested object or collection replaces that whole setting. A 409 target_busy means publishing is in progress; a 409 delivery_conflict means another Target owns the repository tree. Retrieve the Target, resolve the conflict, then retry. See conditional writes.

Deliveries

Targets answer what Typeship maintains. Deliveries answer where it goes and under what identity.

Different Targets may share a repository only when their directories do not overlap. This ownership rule applies across the organization and prevents competing Drafts from replacing each other's files.

Selecting CLI or MCP does not select or bill an SDK Target. Hosted MCP is enabled with the MCP Target by default.

Turning a Target off stops future generation and its hosted service. It does not delete code already delivered or packages already published. Delivery settings remain saved so turning the Target back on does not erase its identity.

Update Deliveries

A Target has at most one Delivery of each type: one repository and, for an MCP Target, one hosted_mcp. Create a Target with its Deliveries in deliveries, then change them one at a time:

With automatic generation on, each change queues the Target's Generation, and a Target already queued or running reuses it. PATCH and DELETE accept If-Match with the Delivery's ETag. A 409 delivery_conflict means another Target owns the repository directory, and a 409 target_busy means the Target is publishing.

For example, move the Parcel MCP Target's repository Delivery into a directory and turn on publishing, leaving its hosted endpoint unchanged:

curl -sS -X PATCH https://typeship.dev/api/v1/deliveries/dlv_... \
  -H "Authorization: Bearer $TYPESHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repository":{"provider":"github","identifier":"parcel/mcp","directory":"packages/mcp","publish_on_merge":true}}'

Package releases

Package versions belong to Targets, not Projects or Specs.

• The latest release advances when a checked Draft with package changes merges. Read the supported, read-only version_current on a Target to see that release version, or null before its first release. The release history records each accepted version.
• The Draft version is automatically the minimum SemVer change required by the cumulative unreleased diff.
• An exact version selected in the Console, API, or release: X.Y.Z PR title may be larger but never smaller.

A checked merge that changes the released package creates an immutable rel_* Release and advances the Console’s latest release. It records the Generation, Spec Revision, repository, and accepted commit. A merge confined to tests or checks updates the code Typeship carries into later Drafts without a new version or release. The latest release remains unchanged; registry publishing starts only when configured. See the two-merge example.

Plans and operation limits

Free lets one Project select any of the five Targets. Each Generation contains 25 operations and says how many were omitted. The complete Spec is still retained, versioned, and diagnosed.

Pro and Enterprise generate the complete Spec for every Target. See Plans and limits.