@typeship-ax/cli 0.22.0 → 0.24.0

package/api.md

@@ -1,8 +1,8 @@
-# typeship — CLI reference
+# Typeship — CLI reference
 
-API version 1.0.0. Package version 0.22.0. Generated by typeship.
+API version 1.0.0. Package version 0.24.0. Generated by Typeship.
 
-Run `typeship help --json` for the command index. Path arguments are positional; flags use the names shown below. Arrays accept repeated flags, comma-separated values, or a JSON array; object values use JSON.
+Run `typeship help --json` for the command index, and `typeship help <resource> <command> --json` for one command's flags. Path arguments are positional; flags use the names shown below. Arrays accept repeated flags, comma-separated values, or a JSON array; object values use JSON.
 
 API commands write JSON to stdout. Exit codes: `0` success, `1` request failure, `2` invalid usage. In agent mode, errors are JSON on stderr with `status`, `issues`, and `next_steps`; branch on `issues[].code`. Destructive operations require `--force` without an interactive terminal.
 
@@ -10,75 +10,43 @@ Use `--fields id,name` to project response fields. `--base-url <url>` overrides
 
 For complete input and output schemas, use [`api.json`](./api.json), the machine-readable companion to this reference.
 
-## generate
-
-### `typeship generate run [flags]`
-
-Generate one package from a Spec
-
-`POST /generate`
+## projects
 
-Safety: **write** · Authentication: **optional**
+### `typeship projects create [flags]`
 
-Returns one generated package without creating a Project.
+Create a Project
 
-Supports [idempotent retries](https://typeship.dev/docs/typeship-api/idempotency); keyed responses include generated files in the replay cache.
+`POST /projects`
 
-Use `download.url` to save the complete ZIP, verify `download.sha256`, and extract it into an empty directory. The link expires at `download.expires_at` and grants access to anyone who has it. CLI, MCP, and SDK calls supply an idempotency key automatically. Agents should request `fields=["download","coverage","warnings","claim"]` to keep the MCP result compact; files can exceed the response limit. Download the ZIP instead of repeating generation to retrieve omitted files.
+Safety: **write** · Authentication: **required**
 
-Anonymous and Free requests include the first 25 operations. Paid plans include all operations. Anonymous requests are rate limited by IP address. Check `coverage` for omitted operations; an invalid API key returns `401`.
+Creates a Project from a URL or GitHub Spec.
+Automatic generation is enabled by default for a saved Project.
 
-An anonymous URL request without source headers may return `claim.url`. Sign in through that link within seven days to save the recipe as a Project.
+Free includes one saved Project, all selected Targets, and the first 25 operations per Target, with regeneration, history, delivery pull requests, and previews. Pro supports additional Projects and all operations. One-shot generation does not use a Project slot.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `--spec` | body | `json` | yes | A Spec for one-shot generation, provided as exactly one URL or inline entrypoint. |
-| `--target` | body | `object` | yes | One-shot generator descriptor; no persisted Target is created. |
-| `--package-name` | body | `string` | no | npm package or Python distribution override. Valid only for the TypeScript and Python SDK targets. |
-| `--module-path` | body | `string` | no | Go module path override for the generated artifact's own module. Valid only for the Go SDK and Go CLI Targets. Projects derive this from the Go destination repository by default. |
-| `--go-sdk` | body | `object` | no | The exact paired Go SDK a go_cli generation is built on. Required when target.type is go_cli and rejected otherwise. The descriptor is closed and immutable, because a CLI that pins a range or a branch pins nothing. |
-| `--config` | body | `object` | no | Everything Typeship needs beyond the Spec, in one object: generation customization (globals, retries, pagination, readme) and how the generated tooling behaves (cli, mcp, package, docs_url). Plain configuration. Typeship never requires vendor extensions inside the Spec itself. One-shot generation also accepts GraphQL settings here; stored projects keep those settings on their Spec. |
+| `--name` | body | `string` | yes | — |
+| `--spec` | body | `object` | yes | — |
+| `--targets` | body | `array` | yes | Initial first-class Targets. More than one may use the same generator with different identities or Deliveries. |
+| `--auto-generate` | body | `boolean` | no | Whether Typeship should regenerate automatically when the source or saved configuration changes. Default: true. |
+| `--config` | body | `json` | no | Shared defaults inherited by every Target. GraphQL settings belong in spec.graphql. |
 | `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship generate run --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' --target '{"type":"cli"}'
-```
-
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
-
-Read the full command contract with `typeship docs generate run --json`.
-
-### `typeship generate download-package [flags]`
-
-Download a generated package
-
-`GET /generate/download`
-
-Safety: **read** · Authentication: **none**
-
-Download the complete ZIP referenced by `generate_run`'s `download.url`. Pass the token from that URL. No API key is needed; the token grants access only to that exact package until its replay window expires. Keep the token private.
-
-The local MCP server saves this binary response to disk. On a hosted MCP connection, download the original URL directly to your workspace. Verify the ZIP against `download.sha256` before extracting it into an empty directory. Expired or invalid tokens return `404`; a new generation creates a new download.
-
-| Argument or flag | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `--query-token` | query | `string` | yes | Private download token from download.url in the generation result. |
-
-```sh
-typeship generate download-package --query-token parcel_download_example_token_1234567890123
+typeship projects create --name 'Parcel API' --spec '{"source":{"type":"url","url":{"url":"https://api.parcel.example/openapi.json"}}}' --targets '[{"name":"Parcel CLI","type":"cli","deliveries":[{"type":"repository","repository":{"provider":"github","identifier":"parcel-example/parcel-client","package_name":"parcel-client","publish_on_merge":false}}]}]'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs generate download-package --json`.
-
-## projects
+Read the full command contract with `typeship docs projects create --json`.
 
 ### `typeship projects list [flags]`
 
-List projects
+List Projects
 
 `GET /projects`
 
@@ -97,41 +65,9 @@ Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` co
 
 Read the full command contract with `typeship docs projects list --json`.
 
-### `typeship projects create [flags]`
-
-Create a project
-
-`POST /projects`
-
-Safety: **write** · Authentication: **required**
-
-Creates a Project from a URL or GitHub Spec.
-Automatic generation is enabled by default for a saved Project.
-
-Free includes one saved Project, all selected Targets, and the first 25 operations per Target, with regeneration, history, delivery pull requests, and previews. Pro supports additional Projects and all operations. One-shot generation does not use a Project slot.
-
-| Argument or flag | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `--name` | body | `string` | yes | — |
-| `--spec` | body | `object` | yes | — |
-| `--targets` | body | `array` | yes | Initial first-class Targets. More than one may use the same generator with different identities or Deliveries. |
-| `--auto-generate` | body | `boolean` | no | Whether Typeship should regenerate automatically when the source or saved configuration changes. Default: true. |
-| `--config` | body | `json` | no | Shared defaults inherited by every Target. GraphQL settings belong in spec.graphql. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
-
-Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
-
-```sh
-typeship projects create --name 'Parcel API' --spec '{"source":{"type":"url","url":{"url":"https://api.parcel.example/openapi.json"}}}' --targets '[{"name":"Parcel CLI","type":"cli","deliveries":[{"type":"repository","repository":{"provider":"github","identifier":"parcel-example/parcel-client","package_name":"parcel-client","publish_on_merge":false}}]}]'
-```
-
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
-
-Read the full command contract with `typeship docs projects create --json`.
-
 ### `typeship projects get <project_id> [flags]`
 
-Get a project
+Get a Project
 
 `GET /projects/{project_id}`
 
@@ -151,67 +87,67 @@ Output: the response payload as JSON on stdout. A successful response without a
 
 Read the full command contract with `typeship docs projects get --json`.
 
-### `typeship projects delete <project_id> [flags]`
+### `typeship projects update <project_id> [flags]`
 
-Delete a project
+Update a Project
 
-`DELETE /projects/{project_id}`
+`PATCH /projects/{project_id}`
 
-Safety: **destructive** · Authentication: **required**
+Safety: **write** · Authentication: **required**
+
+Omitted fields keep their current values. A supplied config replaces the entire stored object; null or an empty object clears it.
+With auto_generate enabled, changing shared config queues a Generation for each Target whose effective config changes. A queued or running Target reuses that Generation.
+Omitting If-Match applies the update to the current resource; with If-Match, a stale ETag returns 412 precondition_failed without saving.
 
-A `502 repository_unavailable` means the Project was not deleted because its release pull requests could not be retired. Retry deletion to finish retiring the remaining reviews. Repeating a completed deletion returns `404`.
+A `409 target_busy` means a Target is publishing. Retrieve the Project, wait for publishing to finish, reconcile your update, and retry.
+A `502 follow_up_failed` means the Project was saved, but an obsolete Draft pull request could not be retired. Retrieve the Project and retry the same update to finish retiring reviews if that update is still desired.
 See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
+| `--name` | body | `string` | no | — |
+| `--auto-generate` | body | `boolean` | no | — |
+| `--config` | body | `json` | no | Replaces the Project's shared Target defaults. Send null to clear them. |
 | `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
+
 ```sh
-typeship projects delete prj_4f8k2m7x9q1v6b3n --force
+typeship projects update prj_4f8k2m7x9q1v6b3n --auto-generate false
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs projects delete --json`.
-
-### `typeship projects update <project_id> [flags]`
+Read the full command contract with `typeship docs projects update --json`.
 
-Update a project
+### `typeship projects delete <project_id> [flags]`
 
-`PATCH /projects/{project_id}`
+Delete a Project
 
-Safety: **write** · Authentication: **required**
+`DELETE /projects/{project_id}`
 
-Omitted fields keep their current values. A supplied config replaces the entire stored object; null or an empty object clears it.
-With auto_generate enabled, changing shared config queues a Generation for each Target whose effective config changes. A queued or running Target reuses that Generation.
-Omitting If-Match applies the update to the current resource; with If-Match, a stale ETag returns 412 precondition_failed without saving.
+Safety: **destructive** · Authentication: **required**
 
-A `409 target_busy` means a Target is publishing. Retrieve the Project, wait for publishing to finish, reconcile your update, and retry.
-A `502 follow_up_failed` means the Project was saved, but an obsolete release pull request could not be retired. Retrieve the Project and retry the same update to finish retiring reviews if that update is still desired.
+A `502 repository_unavailable` means the Project was not deleted because its Draft pull requests could not be retired. Retry deletion to finish retiring the remaining reviews. Repeating a completed deletion returns `404`.
 See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
-| `--name` | body | `string` | no | — |
-| `--auto-generate` | body | `boolean` | no | — |
-| `--config` | body | `json` | no | Replaces the Project's shared Target defaults. Send null to clear them. |
 | `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
-Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
-
 ```sh
-typeship projects update prj_4f8k2m7x9q1v6b3n --auto-generate false
+typeship projects delete prj_4f8k2m7x9q1v6b3n --force
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs projects update --json`.
+Read the full command contract with `typeship docs projects delete --json`.
 
 ### `typeship projects generate <project_id> [flags]`
 
-Start generation for active Targets
+Generate a Project's Targets
 
 `POST /projects/{project_id}/generate`
 
@@ -261,7 +197,7 @@ Read the full command contract with `typeship docs specs get --json`.
 
 ### `typeship specs update <spec_id> [flags]`
 
-Update and resolve a Spec
+Update a Spec
 
 `PATCH /specs/{spec_id}`
 
@@ -296,7 +232,7 @@ Read the full command contract with `typeship docs specs update --json`.
 
 ### `typeship specs refresh <spec_id> [flags]`
 
-Refresh a Spec from its configured source
+Refresh a Spec
 
 `POST /specs/{spec_id}/refresh`
 
@@ -351,12 +287,13 @@ Get a Spec Revision
 
 Safety: **read** · Authentication: **required**
 
-Returns metadata for a saved Spec Revision with a Diagnostics summary. Pass `include=diagnostics` to add every Diagnostic, evaluated with the Spec's current patches and Diagnostic policy. List its source files and resolved document with listSpecRevisionFiles.
+Returns metadata for a saved Spec Revision with a Diagnostics summary. Pass `include=diagnostics` to add every Diagnostic, evaluated with the Spec's current patches and Diagnostic policy. Add `filter=blocking` to receive only the locations that fail the policy, which is what to fix when `diagnostic_summary.status` is blocked. List its source files and resolved document with listSpecRevisionFiles.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<spec_revision_id>` | path | `string` | yes | — |
 | `--include` | query | `string` | no | Add related data to the response. `diagnostics` adds the `diagnostics` and `patch_diagnostics` arrays. |
+| `--filter` | query | `string` | no | Narrow the included Diagnostics to matching locations. Requires include=diagnostics. blocking: locations that fail the Diagnostic policy. introduced: locations new since the baseline. A Diagnostic with no matching location is omitted. diagnostic_summary always describes the complete revision. |
 
 ```sh
 typeship spec-revisions get srev_6m1q8v4k2p9d7h3c
@@ -392,31 +329,9 @@ Read the full command contract with `typeship docs spec-revisions list-files --j
 
 ## targets
 
-### `typeship targets list [flags]`
-
-List Targets
-
-`GET /targets`
-
-Safety: **read** · Authentication: **required**
-
-| Argument or flag | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
-| `--project-id` | query | `string` | no | Only Targets in this Project. Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
-
-```sh
-typeship targets list
-```
-
-Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
-
-Read the full command contract with `typeship docs targets list --json`.
-
 ### `typeship targets create [flags]`
 
-Create an independently configured Target
+Create a Target
 
 `POST /targets`
 
@@ -428,7 +343,6 @@ Creates a Target with its own configuration, Deliveries, and release history. Mu
 | --- | --- | --- | --- | --- |
 | `--project-id` | body | `string` | yes | Unique identifier for a project. Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 | `--name` | body | `string` | yes | — |
-| `--spec-id` | body | `string` | yes | Unique identifier for a project's logical API Spec. |
 | `--type` | body | `string` | yes | Generator implementation selected by a Target. This is configuration, not identity; several Targets may use the same generator. cli is the TypeScript CLI; go_cli is the native Go CLI, a distinct product that imports one exact paired Go SDK module rather than a client of its own. |
 | `--status` | body | `string` | no | Default: "active". |
 | `--release-channel` | body | `string` | no | Default: "stable". |
@@ -440,68 +354,65 @@ Creates a Target with its own configuration, Deliveries, and release history. Mu
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship targets create --project-id prj_4f8k2m7x9q1v6b3n --name 'Parcel CLI' --spec-id spec_2p8m4q7k1v9d6h3c --type cli --config '{"cli":{"command_name":"parcel"}}' --deliveries '[{"type":"repository","repository":{"provider":"github","identifier":"parcel-example/parcel-client","package_name":"parcel-client","publish_on_merge":false}}]'
+typeship targets create --project-id prj_4f8k2m7x9q1v6b3n --name 'Parcel CLI' --type cli --config '{"cli":{"command_name":"parcel"}}' --deliveries '[{"type":"repository","repository":{"provider":"github","identifier":"parcel-example/parcel-client","package_name":"parcel-client","publish_on_merge":false}}]'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
 Read the full command contract with `typeship docs targets create --json`.
 
-### `typeship targets get <target_id> [flags]`
+### `typeship targets list [flags]`
 
-Get a Target
+List Targets
 
-`GET /targets/{target_id}`
+`GET /targets`
 
 Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
+| `--project-id` | query | `string` | no | Only Targets in this Project. Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 
 ```sh
-typeship targets get tgt_5m8q2v7k1p9d4h6c
+typeship targets list
 ```
 
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
-
-Read the full command contract with `typeship docs targets get --json`.
-
-### `typeship targets delete <target_id> [flags]`
+Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
 
-Delete an unused Target
+Read the full command contract with `typeship docs targets list --json`.
 
-`DELETE /targets/{target_id}`
+### `typeship targets get <target_id> [flags]`
 
-Safety: **destructive** · Authentication: **required**
+Get a Target
 
-Deletes a Target with no Generation history, release history, or active Draft. A `409 resource_has_dependencies` means one of those resources still depends on it. Retrieve the Target, disable it instead, or resolve the dependency before retrying.
+`GET /targets/{target_id}`
 
-See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
+Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<target_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
-| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 ```sh
-typeship targets delete tgt_5m8q2v7k1p9d4h6c --force
+typeship targets get tgt_5m8q2v7k1p9d4h6c
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs targets delete --json`.
+Read the full command contract with `typeship docs targets get --json`.
 
 ### `typeship targets update <target_id> [flags]`
 
-Update a Target or its Deliveries
+Update a Target
 
 `PATCH /targets/{target_id}`
 
 Safety: **write** · Authentication: **required**
 
-Omitted fields keep their current values. Supplied config, checks, and deliveries replace their complete stored values.
-With Project auto_generate enabled, changing Target config, checks, or Deliveries queues that Target's Generation. A queued or running Target reuses that Generation.
+Omitted fields keep their current values. Supplied config and checks replace their complete stored values. Change Deliveries with createDelivery, updateDelivery, and deleteDelivery.
+With Project auto_generate enabled, changing Target config or checks queues that Target's Generation. A queued or running Target reuses that Generation.
 Omitting If-Match applies the update to the current resource; with If-Match, a stale ETag returns 412 precondition_failed without saving.
 Select the next version through PATCH /drafts/{draft_id} on the Target's draft_id.
 
@@ -517,7 +428,6 @@ See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writ
 | `--release-channel` | body | `string` | no | — |
 | `--checks` | body | `object` | no | Required checks run against the code in the Draft. Generated checks and customer commands share one reproducible workflow; repository_required names existing repository checks. Supplying checks replaces all settings. Omitted generated restores build, package, and public_entrypoint; omitted repository_required and customer restore empty lists. An empty object restores these defaults. An empty array clears the corresponding list. |
 | `--config` | body | `json` | no | Replaces the complete stored override object. Send null or an empty object to resume Project inheritance. Effective values merge over Project.config; GraphQL settings belong to the Spec. |
-| `--deliveries` | body | `array` | no | Replaces the Delivery set; include each kind you want to keep. Retained kinds preserve their ID, creation time, and hosted URL. Each supplied Delivery replaces its configuration, so omitted optional settings reset to their defaults. Omit deliveries to keep the existing set, or send [] to remove all Deliveries. Removing and later recreating a kind allocates a new ID and, for hosted_mcp, a new URL. |
 | `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
@@ -530,9 +440,34 @@ Output: the response payload as JSON on stdout. A successful response without a
 
 Read the full command contract with `typeship docs targets update --json`.
 
+### `typeship targets delete <target_id> [flags]`
+
+Delete a Target
+
+`DELETE /targets/{target_id}`
+
+Safety: **destructive** · Authentication: **required**
+
+Deletes a Target with no Generation history, release history, or active Draft. A `409 resource_has_dependencies` means one of those resources still depends on it. Retrieve the Target, disable it instead, or resolve the dependency before retrying.
+
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
+
+```sh
+typeship targets delete tgt_5m8q2v7k1p9d4h6c --force
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs targets delete --json`.
+
 ### `typeship targets adopt <target_id> [flags]`
 
-Adopt a verified existing package as the latest release
+Adopt a package release
 
 `POST /targets/{target_id}/adopt`
 
@@ -557,336 +492,379 @@ Output: the response payload as JSON on stdout. A successful response without a
 
 Read the full command contract with `typeship docs targets adopt --json`.
 
-## drafts
+## deliveries
 
-### `typeship drafts list [flags]`
+### `typeship deliveries create [flags]`
 
-List Drafts
+Create a Delivery
 
-`GET /drafts`
+`POST /deliveries`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
 
-Lists open and merged Drafts, newest first. Each Target has one open Draft; each merge adds a merged Draft.
+Adds a repository or hosted MCP Delivery to a Target. A Target has at most one Delivery of each type; a `409 delivery_exists` means it already has one, so update that Delivery instead.
+With Project auto_generate enabled, adding a Delivery queues the Target's Generation. A queued or running Target reuses that Generation.
+
+A `409 delivery_conflict` means another Target owns the requested repository directory. A `409 target_busy` means the Target is publishing; wait for it to finish.
+A `502 follow_up_failed` means the Delivery was saved, but retiring an obsolete review or regenerating the Target failed. Get the Delivery and follow the error's retryable and suggested_action fields.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
+
+```sh
+typeship deliveries create --data '{"target_id":"tgt_5m8q2v7k1p9d4h6c","type":"repository","repository":{"provider":"github","identifier":"parcel-example/parcel-client","package_name":"parcel-client","publish_on_merge":false}}'
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs deliveries create --json`.
+
+### `typeship deliveries list [flags]`
+
+List Deliveries
+
+`GET /deliveries`
+
+Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
 | `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
-| `--target-id` | query | `string` | no | Only Drafts of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
-| `--status` | query | `string` | no | Only Drafts with this status. |
+| `--target-id` | query | `string` | no | Only Deliveries of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 
 ```sh
-typeship drafts list
+typeship deliveries list
 ```
 
 Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
 
-Read the full command contract with `typeship docs drafts list --json`.
+Read the full command contract with `typeship docs deliveries list --json`.
 
-### `typeship drafts get <draft_id> [flags]`
+### `typeship deliveries get <delivery_id> [flags]`
 
-Get a Draft
+Get a Delivery
 
-`GET /drafts/{draft_id}`
+`GET /deliveries/{delivery_id}`
 
 Safety: **read** · Authentication: **required**
 
-Returns the Draft's status. An open Draft also reports its typed reason when action is required, next version and its source, readiness, checks, and conflict counts. The response carries an `ETag`; send it in `If-Match` when updating the Draft to avoid changing a newer version selection.
+Returns the configured repository or hosted MCP Delivery for a Target. A Delivery in another organization returns 404 resource_not_found.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<draft_id>` | path | `string` | yes | — |
+| `<delivery_id>` | path | `string` | yes | — |
 
 ```sh
-typeship drafts get drf_3q7m1v8k2p5d9h4c
+typeship deliveries get dlv_4q8m2v7k1p9d5h6c
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs drafts get --json`.
+Read the full command contract with `typeship docs deliveries get --json`.
 
-### `typeship drafts update <draft_id> [flags]`
+### `typeship deliveries update <delivery_id> [flags]`
 
-Select an exact Draft version or return to automatic versioning
+Update a Delivery
 
-`PATCH /drafts/{draft_id}`
+`PATCH /deliveries/{delivery_id}`
 
 Safety: **write** · Authentication: **required**
 
-Checks your version choice against the required version bump, then regenerates the existing Draft pull request.
+Replaces a repository Delivery's settings. Omitted optional settings reset to their defaults. Hosted MCP Deliveries have no settings to update.
+With Project auto_generate enabled, changing a Delivery queues the Target's Generation. A queued or running Target reuses that Generation.
+Omitting If-Match applies the update to the current Delivery; with If-Match, a stale ETag returns 412 precondition_failed without saving.
 
-Send the Draft's `ETag` in `If-Match` to reject an intervening change with 412 precondition_failed before saving or regenerating. Omitting `If-Match` applies the selection to the current Draft. version_next is required; null restores automatic selection.
-
-A `502` response means the selected version was saved, but regeneration failed. Follow the error's retryable and suggested_action fields. Repeating an unfinished selection resumes generation; repeating a completed selection starts no new work. If using If-Match, retrieve the Draft and confirm the saved selection before retrying with its current ETag.
-A `409 draft_merged` means the Draft merged; retrieve the Target and select a version on its `draft_id`. A `409 target_busy` means the Target is publishing; wait and retry. A `409 version_occupied` means the version is already released; retrieve the Draft and releases, choose a new version, and retry.
-See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
+A `409 delivery_conflict` means another Target owns the requested repository directory. A `409 target_busy` means the Target is publishing; wait for it to finish.
+A `502 follow_up_failed` means the Delivery was saved, but retiring an obsolete review or regenerating the Target failed. Get the Delivery and follow the error's retryable and suggested_action fields.
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<draft_id>` | path | `string` | yes | — |
-| `--version-next` | body | `string` | yes | Exact SemVer, or null to return to automatic selection. |
+| `<delivery_id>` | path | `string` | yes | — |
+| `--repository` | body | `object` | yes | — |
 | `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship drafts update drf_3q7m1v8k2p5d9h4c --version-next 1.1.0
+typeship deliveries update dlv_4q8m2v7k1p9d5h6c --repository '{"provider":"github","identifier":"parcel-example/parcel-client","package_name":"parcel-client","publish_on_merge":true}'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs drafts update --json`.
+Read the full command contract with `typeship docs deliveries update --json`.
 
-### `typeship drafts list-files <draft_id> [flags]`
+### `typeship deliveries delete <delivery_id> [flags]`
 
-List customized and conflicted files on a Draft
+Delete a Delivery
 
-`GET /drafts/{draft_id}/files`
+`DELETE /deliveries/{delivery_id}`
 
-Safety: **read** · Authentication: **required**
+Safety: **destructive** · Authentication: **required**
 
-Lists the Draft's files that differ from the last merged package or need a conflict decision, ordered by path, without file content. Each conflict names its kind, the saved decision, and the sides you can read with getFile. With `filter=history`, lists files affected by a default-branch history rewrite; the list is empty when none is pending.
+Removes a Delivery from its Target. Removing a repository Delivery retires the Target's open Draft pull request; removing a hosted MCP Delivery stops serving its URL. Recreating the type later allocates a new ID and, for hosted MCP, a new URL.
 
-Returns `409 resource_changed` while Typeship is carrying the Draft's latest commit forward (status working), or when the Draft changes between pages.
+A `409 target_busy` means the Target is publishing; wait for it to finish. A `502 follow_up_failed` means the Delivery was removed, but retiring an obsolete review or regenerating the Target failed.
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<draft_id>` | path | `string` | yes | — |
-| `--filter` | query | `string` | no | conflicted: conflicts only. customized: files that differ from the last merged package. history: files affected by a default-branch history rewrite. Omit for conflicted and customized files. |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
+| `<delivery_id>` | path | `string` | yes | — |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 ```sh
-typeship drafts list-files drf_3q7m1v8k2p5d9h4c
+typeship deliveries delete dlv_4q8m2v7k1p9d5h6c --force
 ```
 
-Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs drafts list-files --json`.
+Read the full command contract with `typeship docs deliveries delete --json`.
 
-### `typeship drafts resolve <draft_id> [flags]`
+## generations
 
-Resolve selected Draft files
+### `typeship generations get <generation_id> [flags]`
 
-`POST /drafts/{draft_id}/resolve`
+Get a Generation
 
-Safety: **write** · Authentication: **required**
+`GET /generations/{generation_id}`
 
-Resolves conflicts on the Draft's head_sha: keep yours or generated, or supply final content as text or, for binary files, base64. Choosing generated for a customized path replaces it with the generated file, or deletes a Draft-only file.
+Safety: **read** · Authentication: **required**
 
-Conflict decisions are saved together and can be replaced until applied. Choosing generated for customized paths commits those changes together on the Draft branch. Returns the Draft. When every conflict has a decision, `conflicts.decided` equals `conflicts.total` and Typeship continues the Draft and runs checks. Paths that already match the Draft change nothing.
+Returns the status of that Generation. `queued` and `running` mean generation is still in progress. `completed` means generated files are saved, not that repository delivery or a Draft is complete. List its files with listGenerationFiles and read each with getFile.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<draft_id>` | path | `string` | yes | — |
-| `--expected-head-sha` | body | `string` | yes | The Draft's head_sha. A newer Draft commit returns 409 resource_changed without saving. |
-| `--resolutions` | body | `array` | yes | Unique current conflict or customized paths. Choose generated to discard a customization, including a Draft-only file. Final file content must total at most 2 MiB. Decisions apply together or not at all. |
-
-Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
+| `<generation_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via generations_list). IDs come from generations_list. |
 
 ```sh
-typeship drafts resolve drf_3q7m1v8k2p5d9h4c --expected-head-sha 0123456789abcdef0123456789abcdef01234567 --resolutions '[{"path":"src/index.ts","keep":"content","mode":"100644","content":"export { ParcelClient } from \"./client.js\";\nexport type { Shipment, Label } from \"./types.js\";\nexport { createParcelClient } from \"./helper.js\";\n"}]'
+typeship generations get gen_7h2p5d9c3m8w1k6q
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs drafts resolve --json`.
-
-### `typeship drafts recover <draft_id> [flags]`
+Read the full command contract with `typeship docs generations get --json`.
 
-Approve recovery from rewritten default-branch history
+### `typeship generations list [flags]`
 
-`POST /drafts/{draft_id}/recover`
+List Generations
 
-Safety: **write** · Authentication: **required**
+`GET /generations`
 
-When the Draft has status `action_required` and reason `history_rewritten`, review affected files with `listDraftFiles` and `filter=history`, then approve with the Draft's `history_recovery` revisions. Approval saves the recovery without changing Git and returns the Draft; the next generation rebuilds it from the rewritten default branch. The previous Draft branch stays available, and overlapping code comes back as conflicts to resolve. A rewritten Draft branch alone needs no approval.
+Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<draft_id>` | path | `string` | yes | — |
-| `--expected-default-sha` | body | `string` | yes | The Draft's history_recovery.default_sha. |
-| `--expected-head-sha` | body | `string` | yes | The Draft's history_recovery.head_sha; null when the Draft branch is absent. |
-
-Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
+| `--project-id` | query | `string` | no | Only Generations in this Project. Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
+| `--target-id` | query | `string` | no | Only Generations of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--status` | query | `string` | no | Only Generations with this status. |
 
 ```sh
-typeship drafts recover drf_3q7m1v8k2p5d9h4c --expected-default-sha 89abcdef0123456789abcdef0123456789abcdef --expected-head-sha 0123456789abcdef0123456789abcdef01234567
+typeship generations list
 ```
 
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
-
-Read the full command contract with `typeship docs drafts recover --json`.
+Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
 
-## releases
+Read the full command contract with `typeship docs generations list --json`.
 
-### `typeship releases list [flags]`
+### `typeship generations list-files <generation_id> [flags]`
 
-List releases
+List a Generation's files
 
-`GET /releases`
+`GET /generations/{generation_id}/files`
 
 Safety: **read** · Authentication: **required**
 
+Lists the generated package's files, ordered by path. Read content with getFile.
+
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
+| `<generation_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via generations_list). IDs come from generations_list. |
 | `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
 | `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
-| `--target-id` | query | `string` | no | Only releases of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 
 ```sh
-typeship releases list
+typeship generations list-files gen_7h2p5d9c3m8w1k6q
 ```
 
 Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
 
-Read the full command contract with `typeship docs releases list --json`.
+Read the full command contract with `typeship docs generations list-files --json`.
 
-### `typeship releases get <release_id> [flags]`
+## drafts
 
-Get an immutable release
+### `typeship drafts list [flags]`
 
-`GET /releases/{release_id}`
+List Drafts
+
+`GET /drafts`
 
 Safety: **read** · Authentication: **required**
 
+Lists open and merged Drafts, newest first. Each Target has one open Draft; each merge adds a merged Draft.
+
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<release_id>` | path | `string` | yes | — |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
+| `--target-id` | query | `string` | no | Only Drafts of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--status` | query | `string` | no | Only Drafts with this status. |
 
 ```sh
-typeship releases get rel_7m2q8v4k1p9d5h6c
+typeship drafts list
 ```
 
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
-
-Read the full command contract with `typeship docs releases get --json`.
+Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
 
-### `typeship releases republish <release_id> [flags]`
+Read the full command contract with `typeship docs drafts list --json`.
 
-Retry publishing an exact release
+### `typeship drafts get <draft_id> [flags]`
 
-`POST /releases/{release_id}/republish`
+Get a Draft
 
-Safety: **write** · Authentication: **required**
+`GET /drafts/{draft_id}`
 
-Retries publishing the specified release through its repository workflow. Uses that release's version and accepted commit, even if a newer Draft or release exists.
+Safety: **read** · Authentication: **required**
 
-A `502 repository_unavailable` means the repository publishing workflow could not be dispatched, and nothing was changed.
+Returns the Draft's status. An open Draft also reports its typed reason when action is required, next version and its source, compatibility and version assessment, blocking errors, checks, and conflict counts. The response carries an `ETag`; send it in `If-Match` when updating the Draft to avoid changing a newer version selection.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<release_id>` | path | `string` | yes | — |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `<draft_id>` | path | `string` | yes | — |
 
 ```sh
-typeship releases republish rel_7m2q8v4k1p9d5h6c
+typeship drafts get drf_3q7m1v8k2p5d9h4c
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs releases republish --json`.
+Read the full command contract with `typeship docs drafts get --json`.
 
-## deliveries
+### `typeship drafts update <draft_id> [flags]`
 
-### `typeship deliveries list [flags]`
+Update a Draft
 
-List Deliveries
+`PATCH /drafts/{draft_id}`
 
-`GET /deliveries`
+Safety: **write** · Authentication: **required**
 
-Safety: **read** · Authentication: **required**
+Checks your version choice against the required version bump, then regenerates the existing Draft pull request.
+
+Send the Draft's `ETag` in `If-Match` to reject an intervening change with 412 precondition_failed before saving or regenerating. Omitting `If-Match` applies the selection to the current Draft. version_next is required; null restores automatic selection.
+
+A `502` response means the selected version was saved, but regeneration failed. Follow the error's retryable and suggested_action fields. Repeating an unfinished selection resumes generation; repeating a completed selection starts no new work. If using If-Match, retrieve the Draft and confirm the saved selection before retrying with its current ETag.
+A `409 draft_merged` means the Draft merged; retrieve the Target and select a version on its `draft_id`. A `409 target_busy` means the Target is publishing; wait and retry. A `409 version_occupied` means the version is already released; retrieve the Draft and releases, choose a new version, and retry.
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
-| `--target-id` | query | `string` | no | Only Deliveries of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `<draft_id>` | path | `string` | yes | — |
+| `--version-next` | body | `string` | yes | Exact SemVer, or null to return to automatic selection. |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship deliveries list
+typeship drafts update drf_3q7m1v8k2p5d9h4c --version-next 1.1.0
 ```
 
-Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs deliveries list --json`.
+Read the full command contract with `typeship docs drafts update --json`.
 
-### `typeship deliveries get <delivery_id> [flags]`
+### `typeship drafts list-files <draft_id> [flags]`
 
-Get a Delivery
+List a Draft's files
 
-`GET /deliveries/{delivery_id}`
+`GET /drafts/{draft_id}/files`
 
 Safety: **read** · Authentication: **required**
 
-Returns the configured repository or hosted MCP Delivery for a Target. A Delivery in another organization returns 404 resource_not_found.
+Lists the Draft's files that differ from the last merged package or need a conflict decision, ordered by path, without file content. Each conflict names its kind, the saved decision, and the sides you can read with getFile. With `filter=history`, lists files affected by a default-branch history rewrite; the list is empty when none is pending.
+
+Returns `409 resource_changed` while Typeship is carrying the Draft's latest commit forward (status working), or when the Draft changes between pages.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<delivery_id>` | path | `string` | yes | — |
+| `<draft_id>` | path | `string` | yes | — |
+| `--filter` | query | `string` | no | conflicted: conflicts only. customized: files that differ from the last merged package. history: files affected by a default-branch history rewrite. Omit for conflicted and customized files. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
 
 ```sh
-typeship deliveries get dlv_4q8m2v7k1p9d5h6c
+typeship drafts list-files drf_3q7m1v8k2p5d9h4c
 ```
 
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
 
-Read the full command contract with `typeship docs deliveries get --json`.
+Read the full command contract with `typeship docs drafts list-files --json`.
 
-## publications
+### `typeship drafts resolve <draft_id> [flags]`
 
-### `typeship publications list [flags]`
+Resolve Draft conflicts
 
-List publications
+`POST /drafts/{draft_id}/resolve`
 
-`GET /publications`
+Safety: **write** · Authentication: **required**
 
-Safety: **read** · Authentication: **required**
+Resolves conflicts on the Draft's head_sha: keep yours or generated, or supply final content as text or, for binary files, base64. Choosing generated for a customized path replaces it with the generated file, or deletes a Draft-only file.
+
+Conflict decisions are saved together and can be replaced until applied. Choosing generated for customized paths commits those changes together on the Draft branch. Returns the Draft. When every conflict has a decision, `conflicts.decided` equals `conflicts.total` and Typeship continues the Draft and runs checks. Paths that already match the Draft change nothing.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
-| `--release-id` | query | `string` | no | Only publications of this release. |
+| `<draft_id>` | path | `string` | yes | — |
+| `--expected-head-sha` | body | `string` | yes | The Draft's head_sha. A newer Draft commit returns 409 resource_changed without saving. |
+| `--resolutions` | body | `array` | yes | Unique current conflict or customized paths. Choose generated to discard a customization, including a Draft-only file. Final file content must total at most 2 MiB. Decisions apply together or not at all. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship publications list
+typeship drafts resolve drf_3q7m1v8k2p5d9h4c --expected-head-sha 0123456789abcdef0123456789abcdef01234567 --resolutions '[{"path":"src/index.ts","keep":"content","mode":"100644","content":"export { ParcelClient } from \"./client.js\";\nexport type { Shipment, Label } from \"./types.js\";\nexport { createParcelClient } from \"./helper.js\";\n"}]'
 ```
 
-Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs publications list --json`.
+Read the full command contract with `typeship docs drafts resolve --json`.
 
-### `typeship publications get <publication_id> [flags]`
+### `typeship drafts recover <draft_id> [flags]`
 
-Get publishing status
+Recover a Draft's history
 
-`GET /publications/{publication_id}`
+`POST /drafts/{draft_id}/recover`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
 
-Returns the registry publishing status for a release. A status in another organization returns 404 resource_not_found.
+When the Draft has status `action_required` and reason `history_rewritten`, review affected files with `listDraftFiles` and `filter=history`, then approve with the Draft's `history_recovery` revisions. Approval saves the recovery without changing Git and returns the Draft; the next generation rebuilds it from the rewritten default branch. The previous Draft branch stays available, and overlapping code comes back as conflicts to resolve. A rewritten Draft branch alone needs no approval.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<publication_id>` | path | `string` | yes | — |
+| `<draft_id>` | path | `string` | yes | — |
+| `--expected-default-sha` | body | `string` | yes | The Draft's history_recovery.default_sha. |
+| `--expected-head-sha` | body | `string` | yes | The Draft's history_recovery.head_sha; null when the Draft branch is absent. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship publications get pub_2m8q4v7k1p9d5h6c
+typeship drafts recover drf_3q7m1v8k2p5d9h4c --expected-default-sha 89abcdef0123456789abcdef0123456789abcdef --expected-head-sha 0123456789abcdef0123456789abcdef01234567
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs publications get --json`.
+Read the full command contract with `typeship docs drafts recover --json`.
 
-## generations
+## releases
 
-### `typeship generations list [flags]`
+### `typeship releases list [flags]`
 
-List generations
+List Releases
 
-`GET /generations`
+`GET /releases`
 
 Safety: **read** · Authentication: **required**
 
@@ -894,69 +872,68 @@ Safety: **read** · Authentication: **required**
 | --- | --- | --- | --- | --- |
 | `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
 | `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
-| `--project-id` | query | `string` | no | Only Generations in this Project. Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
-| `--target-id` | query | `string` | no | Only Generations of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
-| `--status` | query | `string` | no | Only Generations with this status. |
+| `--target-id` | query | `string` | no | Only releases of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 
 ```sh
-typeship generations list
+typeship releases list
 ```
 
 Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
 
-Read the full command contract with `typeship docs generations list --json`.
+Read the full command contract with `typeship docs releases list --json`.
 
-### `typeship generations get <generation_id> [flags]`
+### `typeship releases get <release_id> [flags]`
 
-Get a generation
+Get a Release
 
-`GET /generations/{generation_id}`
+`GET /releases/{release_id}`
 
 Safety: **read** · Authentication: **required**
 
-Returns the status of that Generation. `queued` and `running` mean generation is still in progress. `completed` means generated files are saved, not that repository delivery or a Draft is complete. List its files with listGenerationFiles and read each with getFile.
-
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<generation_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via generations_list). IDs come from generations_list. |
+| `<release_id>` | path | `string` | yes | — |
 
 ```sh
-typeship generations get gen_7h2p5d9c3m8w1k6q
+typeship releases get rel_7m2q8v4k1p9d5h6c
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs generations get --json`.
+Read the full command contract with `typeship docs releases get --json`.
 
-### `typeship generations list-files <generation_id> [flags]`
+### `typeship releases retry <release_id> [flags]`
 
-List a Generation's files
+Retry publishing a Release
 
-`GET /generations/{generation_id}/files`
+`POST /releases/{release_id}/retry`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
 
-Lists the generated package's files, ordered by path. Read content with getFile.
+Queues every failed or queued Publication of the release and starts its repository publishing workflow again. Publishing uses that release's version and accepted commit, even if a newer Draft or release exists. Completed Publications are not repeated.
+
+Returns `202` with the Release. Get the Release until each Publication reaches `completed` or `failed`.
+
+A `409 publication_not_retryable` means no Publication is queued or failed. A `502 repository_unavailable` means the repository publishing workflow could not be dispatched, and nothing was changed.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<generation_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via generations_list). IDs come from generations_list. |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
+| `<release_id>` | path | `string` | yes | — |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 ```sh
-typeship generations list-files gen_7h2p5d9c3m8w1k6q
+typeship releases retry rel_7m2q8v4k1p9d5h6c
 ```
 
-Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Read the full command contract with `typeship docs generations list-files --json`.
+Read the full command contract with `typeship docs releases retry --json`.
 
 ## files
 
 ### `typeship files get <file_id> [flags]`
 
-Get a file
+Get a File
 
 `GET /files/{file_id}`
 
@@ -977,11 +954,75 @@ Output: the response payload as JSON on stdout. A successful response without a
 
 Read the full command contract with `typeship docs files get --json`.
 
+## packages
+
+### `typeship packages generate [flags]`
+
+Generate a package
+
+`POST /generate`
+
+Safety: **write** · Authentication: **optional**
+
+Returns one generated package without creating a Project.
+
+Supports [idempotent retries](https://typeship.dev/docs/typeship-api/idempotency); keyed responses include generated files in the replay cache.
+
+Use `download.url` to save the complete ZIP, verify `download.sha256`, and extract it into an empty directory. The link expires at `download.expires_at` and grants access to anyone who has it. CLI, MCP, and SDK calls supply an idempotency key automatically. Agents should request `fields=["download","coverage","warnings","claim"]` to keep the MCP result compact; files can exceed the response limit. Download the ZIP instead of repeating generation to retrieve omitted files.
+
+Anonymous and Free requests include the first 25 operations. Paid plans include all operations. Anonymous requests are rate limited by IP address. Check `coverage` for omitted operations; an invalid API key returns `401`.
+
+An anonymous URL request without source headers may return `claim.url`. Sign in through that link within seven days to save the recipe as a Project.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `--spec` | body | `json` | yes | A Spec for one-shot generation, provided as exactly one URL or inline entrypoint. |
+| `--target` | body | `object` | yes | One-shot generator descriptor; no persisted Target is created. |
+| `--package-name` | body | `string` | no | npm package or Python distribution override. Valid only for the TypeScript and Python SDK targets. |
+| `--module-path` | body | `string` | no | Go module path override for the generated artifact's own module. Valid only for the Go SDK and Go CLI Targets. Projects derive this from the Go destination repository by default. |
+| `--go-sdk` | body | `object` | no | The exact paired Go SDK a go_cli generation is built on. Required when target.type is go_cli and rejected otherwise. The descriptor is closed and immutable, because a CLI that pins a range or a branch pins nothing. |
+| `--config` | body | `object` | no | Everything Typeship needs beyond the Spec, in one object: generation customization (globals, retries, pagination, readme) and how the generated tooling behaves (cli, mcp, package, docs_url). Plain configuration. Typeship never requires vendor extensions inside the Spec itself. One-shot generation also accepts GraphQL settings here; stored projects keep those settings on their Spec. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
+
+```sh
+typeship packages generate --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' --target '{"type":"cli"}'
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs packages generate --json`.
+
+### `typeship packages download [flags]`
+
+Download a generated package
+
+`GET /generate/download`
+
+Safety: **read** · Authentication: **none**
+
+Download the complete ZIP referenced by `packages_generate`'s `download.url`. Pass the token from that URL. No API key is needed; the token grants access only to that exact package until its replay window expires. Keep the token private.
+
+The local MCP server saves this binary response to disk. On a hosted MCP connection, download the original URL directly to your workspace. Verify the ZIP against `download.sha256` before extracting it into an empty directory. Expired or invalid tokens return `404`; a new generation creates a new download.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `--query-token` | query | `string` | yes | Private download token from download.url in the generation result. |
+
+```sh
+typeship packages download --query-token parcel_download_example_token_1234567890123
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs packages download --json`.
+
 ## organization
 
 ### `typeship organization get [flags]`
 
-The organization behind the presented credentials
+Get the Organization
 
 `GET /organization`
 
@@ -1013,6 +1054,7 @@ Lists key metadata and the last four characters of each key. Full keys are not r
 | --- | --- | --- | --- | --- |
 | `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 input_invalid. List query parameters must appear only once; repeated or unrecognized parameters return 400 query_param_invalid. Default: 20. |
 | `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, operation, filters, and ordering that issued it. Omit to start at the first page. Empty or malformed cursors, and cursors issued for different filters, return 400 cursor_invalid; start again from the first page. Repeated cursors return 400 query_param_invalid. The page limit may change between requests. |
+| `--status` | query | `string` | no | Only keys with this status. |
 
 ```sh
 typeship api-keys list
@@ -1048,11 +1090,11 @@ Read the full command contract with `typeship docs api-keys get --json`.
 
 Revoke an API key
 
-`DELETE /api-keys/{api_key_id}`
+`POST /api-keys/{api_key_id}/revoke`
 
-Safety: **destructive** · Authentication: **required**
+Safety: **write** · Authentication: **required**
 
-Revokes a key. Repeating the request returns the same result.
+Revokes a key immediately. The key stays listed with `status: revoked`. Repeating the request returns the same result.
 
 With OAuth, members can revoke their own keys; organization admins can revoke any key. Organization API keys can revoke any key in their organization.
 See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
@@ -1063,7 +1105,7 @@ See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writ
 | `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 ```sh
-typeship api-keys revoke apikey_2nY8mR6pQ4vK9cH3 --force
+typeship api-keys revoke apikey_2nY8mR6pQ4vK9cH3
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.