@typeship-ax/cli 0.10.0 → 0.21.0

package/api.md

@@ -1,6 +1,6 @@
 # typeship — CLI reference
 
-API version 1.0.0. Package version 0.10.0. Generated by typeship; regenerate rather than editing.
+API version 1.0.0. Package version 0.21.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.
 
@@ -14,40 +14,66 @@ For complete input and output schemas, use [`api.json`](./api.json), the machine
 
 ### `typeship generate run [flags]`
 
-Generate one Target from a Definition
+Generate one package from a Spec
 
 `POST /generate`
 
 Safety: **write** · Authentication: **optional**
 
-Stateless generation: nothing is stored. Returns the full generated
-package as files. Works without an API key: anonymous calls generate
-the first 25 operations, rate limited per IP address, and the
-response's `limits` object says what was held back and where to lift
-it; anonymous calls from a Definition URL also carry `claim.url`, a link
-that turns the run into a project once a person signs in. With a key, the free plan generates the first 25 operations and
-paid plans generate the complete Definition. A present but invalid key is a
-401, not a downgrade to anonymous.
+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 |
 | --- | --- | --- | --- | --- |
-| `--definition` | body | `json` | yes | A Definition for stateless generation, provided as exactly one URL or inline entrypoint. |
-| `--target` | body | `object` | yes | Stateless generator descriptor; no persisted Target is created. |
+| `--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. Valid only for the Go SDK. Linked projects derive this from the Go destination repository by default. |
-| `--config` | body | `object` | no | Everything Typeship needs beyond the Definition, 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 Definition itself. Stateless generation also accepts GraphQL settings here; stored projects keep those settings on their Definition. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--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 generate run --definition '{"url":"https://example.com"}' --target '{"generator":"typescript-sdk"}'
+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
+```
+
+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
 
 ### `typeship projects list [flags]`
@@ -60,8 +86,8 @@ Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
 typeship projects list
@@ -79,49 +105,51 @@ Create a project
 
 Safety: **write** · Authentication: **required**
 
-Stores a URL- or GitHub-sourced project. Free includes one stored project, every selected target, and the first 25 operations, while keeping manual and automatic regeneration, history, destination pull requests, and preview checks. Stateless POST /generate does not consume this slot. Pro adds projects and generates every operation in the Definition.
+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 | — |
-| `--definition` | body | `object` | 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 changes. Default: false. |
-| `--relay-enabled` | body | `boolean` | no | Enable webhook relay sessions. Requires the CLI target and Pro. Default: false. |
-| `--config` | body | `json` | no | Shared defaults inherited by every Target. GraphQL settings belong in definition.graphql. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--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 example --definition '{"source":{"kind":"url","url":"https://example.com"}}' --targets '[{"name":"example","generator":"typescript-sdk"}]'
+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 retrieve <project_id> [flags]`
+### `typeship projects get <project_id> [flags]`
 
-Retrieve a project
+Get a project
 
 `GET /projects/{project_id}`
 
 Safety: **read** · Authentication: **required**
 
-Returns Project-owned fields only. List Targets separately for Target and Delivery data.
+Returns the Project's settings and Spec ID. List its Targets separately to retrieve Target configuration and Deliveries.
 
 | 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. |
 
 ```sh
-typeship projects retrieve prj_4f8k2m7x9q1v6b3n
+typeship projects get prj_4f8k2m7x9q1v6b3n
 ```
 
 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 retrieve --json`.
+Read the full command contract with `typeship docs projects get --json`.
 
 ### `typeship projects delete <project_id> [flags]`
 
@@ -131,9 +159,13 @@ Delete a project
 
 Safety: **destructive** · Authentication: **required**
 
+A `502` response 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`.
+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. |
+| `--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 projects delete prj_4f8k2m7x9q1v6b3n --force
@@ -151,281 +183,273 @@ Update a project
 
 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 `409 target_busy` means a Target is publishing. Retrieve the Project, wait for publishing to finish, reconcile your update, and retry.
+A `502` response 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.
+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 | — |
-| `--relay-enabled` | body | `boolean` | no | Enable webhook relay sessions. Requires the CLI target and Pro. |
 | `--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
+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 update --json`.
 
-### `typeship projects retrieve-diagnostics <project_id> [flags]`
+### `typeship projects generate <project_id> [flags]`
 
-Analyze a project's latest Definition Revision
+Start generation for active Targets
 
-`GET /projects/{project_id}/diagnostics`
+`POST /projects/{project_id}/generate`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
 
-Runs deterministic OpenAPI or GraphQL authorship checks against the latest observed immutable Definition Revision after applying the Definition's existing patches. Diagnostics group every affected location under a stable rule. Exact patches are included only when Typeship can derive the change without inventing API behavior.
+Queues one Generation per active Target and returns their IDs. Retrieve each Generation until its status moves from `queued` to `running` and then `completed` or `failed`. `completed` means generated files are saved; check Delivery and Draft status separately for repository delivery and pull requests. A Target already queued or running is returned without starting another Generation. A matching Idempotency-Key replay returns the same Generations with their current statuses.
+
+If the package already matches a destination and no Draft is open, delivery creates no commit, branch, or pull request. An existing Draft stays open. Automatic generation uses the same workflow.
 
 | 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. |
+| `--target-id` | body | `string` | no | Stable identifier for one configured generated product. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--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 retrieve-diagnostics prj_4f8k2m7x9q1v6b3n
+typeship projects generate prj_4f8k2m7x9q1v6b3n --target-id 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 projects retrieve-diagnostics --json`.
+Read the full command contract with `typeship docs projects generate --json`.
 
-### `typeship projects refresh-diagnostics <project_id> [flags]`
+## specs
 
-Refresh a project's Diagnostics from its configured source
+### `typeship specs get <spec_id> [flags]`
 
-`POST /projects/{project_id}/diagnostics`
+Get a Spec
 
-Safety: **write** · Authentication: **required**
+`GET /specs/{spec_id}`
 
-Fetches the complete configured source, records a new immutable revision only when content changed, and returns its Diagnostics. This does not generate targets or consume a metered generation.
+Safety: **read** · Authentication: **required**
 
 | 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. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `<spec_id>` | path | `string` | yes | — |
 
 ```sh
-typeship projects refresh-diagnostics prj_4f8k2m7x9q1v6b3n
+typeship specs get spec_2p8m4q7k1v9d6h3c
 ```
 
 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 refresh-diagnostics --json`.
+Read the full command contract with `typeship docs specs get --json`.
 
-### `typeship projects remediate-diagnostics <project_id> [flags]`
+### `typeship specs update <spec_id> [flags]`
 
-Apply exact, reviewed diagnostic remediations
+Update and resolve a Spec
 
-`POST /projects/{project_id}/diagnostics/remediations`
+`PATCH /specs/{spec_id}`
 
 Safety: **write** · Authentication: **required**
 
-Applies only deterministic patches. Repository sources receive an updateable source pull request; URL sources receive project overlays. Diagnostics that require API-owner intent return 422 and include an authoring_brief in the Diagnostic instead.
+Resolves the source files before saving the update and records a new Spec Revision when the source changes.
+Omitted fields remain unchanged; supplied objects and arrays replace the whole field.
+If the Spec or its Project configuration changes during validation, returns 409 resource_changed without saving the rejected update. Retrieve the current Spec and Project, reconcile your changes,
+and submit a new request with a new Idempotency-Key if using one.
+
+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. |
-| `--diagnostic-ids` | body | `array` | yes | Stable IDs of current diagnostics whose exact patches should be reviewed and applied. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `<spec_id>` | path | `string` | yes | — |
+| `--source` | body | `json` | no | — |
+| `--patches` | body | `array` | no | Replace all patches in order. An empty array removes every patch; null is invalid. |
+| `--graphql` | body | `json` | no | Replace all GraphQL settings. Null or an empty object clears them. |
+| `--diagnostic-policy` | body | `object` | no | Source pull-request enforcement threshold, new-versus-complete baseline, and explicitly reviewed rule or location exceptions. |
+| `--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. |
+| `--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 remediate-diagnostics prj_4f8k2m7x9q1v6b3n --diagnostic-ids '["value"]'
+typeship specs update spec_2p8m4q7k1v9d6h3c --source '{"type":"url","url":{"url":"https://api.parcel.example/openapi.json"}}'
 ```
 
 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 remediate-diagnostics --json`.
+Read the full command contract with `typeship docs specs update --json`.
 
-### `typeship projects retrieve-integration-health <project_id> [flags]`
+### `typeship specs refresh <spec_id> [flags]`
 
-Diagnose a project's repository integrations
+Refresh a Spec from its configured source
 
-`GET /projects/{project_id}/integration-health`
+`POST /specs/{spec_id}/refresh`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
 
-Returns provider-neutral, machine-actionable source and destination access, Definition readability, source-approval label setup, required status names, and the latest durable webhook delivery. The Console renders this same result.
+Fetches the configured source now and creates a new Spec Revision only when its content changes. Diagnostics then reads that revision. If automatic generation is enabled, refresh queues generation for active Targets even when the source is unchanged.
 
 | 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. |
+| `<spec_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 projects retrieve-integration-health prj_4f8k2m7x9q1v6b3n
+typeship specs refresh spec_2p8m4q7k1v9d6h3c
 ```
 
 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 retrieve-integration-health --json`.
+Read the full command contract with `typeship docs specs refresh --json`.
+
+## specRevisions
 
-### `typeship projects list-generations <project_id> [flags]`
+### `typeship spec-revisions list [flags]`
 
-List a project's generations
+List Spec Revisions
 
-`GET /projects/{project_id}/generations`
+`GET /spec-revisions`
 
 Safety: **read** · Authentication: **required**
 
+Lists Spec Revisions, newest first. Source content is not included; list a revision's files with listSpecRevisionFiles.
+
 | 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. |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
-| `--target-id` | query | `string` | no | Only generations for this persisted Target. |
+| `--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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
+| `--spec-id` | query | `string` | no | Only revisions of this Spec. |
 
 ```sh
-typeship projects list-generations prj_4f8k2m7x9q1v6b3n
+typeship spec-revisions 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 projects list-generations --json`.
+Read the full command contract with `typeship docs spec-revisions list --json`.
 
-### `typeship projects generate <project_id> [flags]`
+### `typeship spec-revisions get <spec_revision_id> [flags]`
 
-Generate targets and open pull requests
+Get a Spec Revision
 
-`POST /projects/{project_id}/generations`
+`GET /spec-revisions/{spec_revision_id}`
 
-Safety: **write** · Authentication: **required**
+Safety: **read** · Authentication: **required**
 
-Resolves the project's URL or GitHub source, generates every
-configured delivery package, stores each result in the project's history,
-and attempts to open a pull request in every configured destination.
-When the complete generated tree already matches a destination, no
-commit, branch, or pull request is created and that generation reports
-`pr_status: no_changes`. This is the same pipeline automatic
-regeneration runs after a source change.
+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.
 
 | 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. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `<spec_revision_id>` | path | `string` | yes | — |
+| `--include` | query | `string` | no | Add related data to the response. `diagnostics` adds the `diagnostics` and `patch_diagnostics` arrays. |
 
 ```sh
-typeship projects generate prj_4f8k2m7x9q1v6b3n
+typeship spec-revisions get srev_6m1q8v4k2p9d7h3c
 ```
 
 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 generate --json`.
-
-## definitions
+Read the full command contract with `typeship docs spec-revisions get --json`.
 
-### `typeship definitions retrieve <definition_id> [flags]`
+### `typeship spec-revisions list-files <spec_revision_id> [flags]`
 
-Retrieve a Definition
+List a Spec Revision's files
 
-`GET /definitions/{definition_id}`
+`GET /spec-revisions/{spec_revision_id}/files`
 
 Safety: **read** · Authentication: **required**
 
-| Argument or flag | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `<definition_id>` | path | `string` | yes | — |
-
-```sh
-typeship definitions retrieve def_2p8m4q7k1v9d6h3c
-```
-
-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 definitions retrieve --json`.
-
-### `typeship definitions update <definition_id> [flags]`
-
-Update and resolve a Definition
-
-`PATCH /definitions/{definition_id}`
-
-Safety: **write** · Authentication: **required**
-
-Resolves the complete document graph and records a new immutable revision before saving.
+Lists the captured source files and the resolved document Typeship generated from, ordered by path. Read content with getFile.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<definition_id>` | path | `string` | yes | — |
-| `--source` | body | `json` | no | — |
-| `--patches` | body | `array` | no | — |
-| `--graphql` | body | `json` | no | — |
-| `--diagnostic-policy` | body | `object` | no | Source pull-request enforcement threshold, new-versus-complete baseline, and explicitly reviewed rule or location exceptions. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, 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.
+| `<spec_revision_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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
-typeship definitions update def_2p8m4q7k1v9d6h3c
+typeship spec-revisions list-files srev_6m1q8v4k2p9d7h3c
 ```
 
-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 definitions update --json`.
+Read the full command contract with `typeship docs spec-revisions list-files --json`.
 
 ## targets
 
-### `typeship targets list <project_id> [flags]`
+### `typeship targets list [flags]`
 
-List a project's Targets
+List Targets
 
-`GET /projects/{project_id}/targets`
+`GET /targets`
 
 Safety: **read** · Authentication: **required**
 
 | 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. |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. 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 prj_4f8k2m7x9q1v6b3n
+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 <project_id> [flags]`
+### `typeship targets create [flags]`
 
 Create an independently configured Target
 
-`POST /projects/{project_id}/targets`
+`POST /targets`
 
 Safety: **write** · Authentication: **required**
 
-Several Targets may use the same generator with distinct configuration, Deliveries, and release streams.
+Creates a Target with its own configuration, Deliveries, and release history. Multiple Targets can use the same generator.
 
 | 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. |
+| `--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 | — |
-| `--definition-id` | body | `string` | yes | Unique identifier for a project's logical API Definition. |
-| `--generator` | body | `string` | yes | Generator implementation selected by a Target. This is configuration, not identity; several Targets may use the same generator. |
-| `--state` | body | `string` | no | Default: "active". |
-| `--edition` | body | `string` | no | Default: "2026-08-24". |
+| `--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". |
-| `--proposed-version` | body | `string` | no | Optional larger or prerelease SemVer for the next reviewed release. |
-| `--config` | body | `json` | no | Target-specific overrides merged over Project.config. GraphQL settings are rejected here and belong to the Definition. |
+| `--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 | Target-specific overrides merged over Project.config. GraphQL settings are rejected here and belong to the Spec. |
 | `--deliveries` | body | `array` | no | — |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--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 targets create prj_4f8k2m7x9q1v6b3n --name example --definition-id def_2p8m4q7k1v9d6h3c --generator typescript-sdk
+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}}]'
 ```
 
 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 retrieve <target_id> [flags]`
+### `typeship targets get <target_id> [flags]`
 
-Retrieve a Target
+Get a Target
 
 `GET /targets/{target_id}`
 
@@ -433,15 +457,15 @@ Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
+| `<target_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 
 ```sh
-typeship targets retrieve tgt_5m8q2v7k1p9d4h6c
+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 retrieve --json`.
+Read the full command contract with `typeship docs targets get --json`.
 
 ### `typeship targets delete <target_id> [flags]`
 
@@ -451,11 +475,14 @@ Delete an unused Target
 
 Safety: **destructive** · Authentication: **required**
 
-Targets with Generation or release history, or an active release candidate, must be disabled instead.
+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 | — |
+| `<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
@@ -467,331 +494,508 @@ Read the full command contract with `typeship docs targets delete --json`.
 
 ### `typeship targets update <target_id> [flags]`
 
-Update a Target, its Deliveries, or its next reviewed version
+Update a Target or its Deliveries
 
 `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.
+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.
+
+A `409 target_busy` means the Target is publishing; wait for it to finish. A `409 delivery_conflict` means another Target owns the requested repository tree; retrieve both Targets, choose a free destination, and retry.
+A `502` response means the update was saved, but retiring an obsolete review or regenerating the Target failed. Retrieve the Target 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 |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
+| `<target_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 | `--name` | body | `string` | no | — |
-| `--state` | body | `string` | no | — |
-| `--edition` | body | `string` | no | — |
+| `--status` | body | `string` | no | — |
 | `--release-channel` | body | `string` | no | — |
-| `--proposed-version` | body | `string` | no | — |
-| `--config` | body | `json` | no | Target-specific overrides merged over Project.config. GraphQL settings are rejected here and belong to the Definition. |
-| `--deliveries` | body | `array` | 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.
 
 ```sh
-typeship targets update tgt_5m8q2v7k1p9d4h6c
+typeship targets update tgt_5m8q2v7k1p9d4h6c --status disabled
 ```
 
 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 update --json`.
 
-### `typeship targets list-releases <target_id> [flags]`
+### `typeship targets adopt <target_id> [flags]`
 
-List immutable releases for a Target
+Adopt a verified existing package as the latest release
 
-`GET /targets/{target_id}/releases`
+`POST /targets/{target_id}/adopt`
+
+Safety: **write** · Authentication: **required**
+
+Checks the repository tag, package metadata, and registry artifact, then records the package as an Imported latest release. Opens the first Typeship Draft at the next major version; review it to establish the baseline for preserving existing code.
+
+| 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. |
+| `--body-version` | body | `string` | yes | Exact already-published package version to make the latest release. |
+| `--tag` | body | `string` | yes | Immutable repository tag containing the matching package source. |
+| `--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 targets adopt tgt_5m8q2v7k1p9d4h6c --body-version 1.0.0 --tag v1.0.0
+```
+
+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 adopt --json`.
+
+## drafts
+
+### `typeship drafts list [flags]`
+
+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 |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. 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 targets list-releases tgt_5m8q2v7k1p9d4h6c
+typeship drafts 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-releases --json`.
+Read the full command contract with `typeship docs drafts list --json`.
 
-### `typeship targets retrieve-draft <target_id> [flags]`
+### `typeship drafts get <draft_id> [flags]`
 
-Retrieve a Target's rolling Draft release
+Get a Draft
 
-`GET /targets/{target_id}/draft`
+`GET /drafts/{draft_id}`
 
 Safety: **read** · Authentication: **required**
 
-Returns Current, the cumulative Draft version and readiness, its exact head, and the optimistic release revision.
+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.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
+| `<draft_id>` | path | `string` | yes | — |
 
 ```sh
-typeship targets retrieve-draft tgt_5m8q2v7k1p9d4h6c
+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 targets retrieve-draft --json`.
+Read the full command contract with `typeship docs drafts get --json`.
 
-### `typeship targets update-draft <target_id> [flags]`
+### `typeship drafts update <draft_id> [flags]`
 
 Select an exact Draft version or return to automatic versioning
 
-`PATCH /targets/{target_id}/draft`
+`PATCH /drafts/{draft_id}`
 
 Safety: **write** · Authentication: **required**
 
-Validates the selection against the cumulative required bump and regenerates the same rolling Draft pull request.
+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 |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
-| `--body-version` | body | `string` | yes | Exact SemVer, or null to return to automatic selection. |
-| `--expected-revision` | body | `number` | no | — |
+| `<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 targets update-draft tgt_5m8q2v7k1p9d4h6c --body-version 1.0.0
+typeship drafts update drf_3q7m1v8k2p5d9h4c --version-next 1.1.0
 ```
 
 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 update-draft --json`.
+Read the full command contract with `typeship docs drafts update --json`.
 
-### `typeship targets adopt-release <target_id> [flags]`
+### `typeship drafts list-files <draft_id> [flags]`
 
-Adopt a verified existing package as Current
+List customized and conflicted files on a Draft
 
-`POST /targets/{target_id}/adopt`
+`GET /drafts/{draft_id}/files`
+
+Safety: **read** · 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.
+
+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 |
+| --- | --- | --- | --- | --- |
+| `<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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
+
+```sh
+typeship drafts list-files drf_3q7m1v8k2p5d9h4c
+```
+
+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-files --json`.
+
+### `typeship drafts resolve <draft_id> [flags]`
+
+Resolve selected Draft files
+
+`POST /drafts/{draft_id}/resolve`
 
 Safety: **write** · Authentication: **required**
 
-Verifies the repository tag, package metadata, and registry artifact; records an Imported Current release; then opens the first Typeship Draft at the next major version because no trusted generated baseline exists yet.
+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 |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
-| `--body-version` | body | `string` | yes | Exact already-published package version to make Current. |
-| `--tag` | body | `string` | yes | Immutable repository tag containing the matching package source. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, 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 | — |
+| `--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 targets adopt-release tgt_5m8q2v7k1p9d4h6c --body-version 1.0.0 --tag value
+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: 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 adopt-release --json`.
+Read the full command contract with `typeship docs drafts resolve --json`.
+
+### `typeship drafts recover <draft_id> [flags]`
 
-### `typeship targets retrieve-release <target_release_id> [flags]`
+Approve recovery from rewritten default-branch history
 
-Retrieve an immutable Target release
+`POST /drafts/{draft_id}/recover`
+
+Safety: **write** · Authentication: **required**
 
-`GET /target_releases/{target_release_id}`
+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 |
+| --- | --- | --- | --- | --- |
+| `<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 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 drafts recover --json`.
+
+## releases
+
+### `typeship releases list [flags]`
+
+List releases
+
+`GET /releases`
 
 Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. 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 targets retrieve-release rel_7m2q8v4k1p9d5h6c
+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 releases list --json`.
+
+### `typeship releases get <release_id> [flags]`
+
+Get an immutable release
+
+`GET /releases/{release_id}`
+
+Safety: **read** · Authentication: **required**
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<release_id>` | path | `string` | yes | — |
+
+```sh
+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 targets retrieve-release --json`.
+Read the full command contract with `typeship docs releases get --json`.
 
-### `typeship targets republish-release <target_release_id> [flags]`
+### `typeship releases republish <release_id> [flags]`
 
-Retry publication of an exact Target release
+Retry publishing an exact release
 
-`POST /target_releases/{target_release_id}/republish`
+`POST /releases/{release_id}/republish`
 
 Safety: **write** · Authentication: **required**
 
-Dispatches the repository-owned republish workflow for this immutable version and accepted commit. It never selects the latest Draft or release.
+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.
+
+A `502` response means the repository publishing workflow could not be dispatched.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_release_id>` | path | `string` | yes | — |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `<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 targets republish-release rel_7m2q8v4k1p9d5h6c
+typeship releases republish 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 targets republish-release --json`.
+Read the full command contract with `typeship docs releases republish --json`.
 
-## generations
+## deliveries
 
-### `typeship generations retrieve <generation_id> [flags]`
+### `typeship deliveries list [flags]`
 
-Retrieve a generation
+List Deliveries
 
-`GET /generations/{generation_id}`
+`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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. 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. |
+
+```sh
+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 deliveries list --json`.
+
+### `typeship deliveries get <delivery_id> [flags]`
+
+Get a Delivery
+
+`GET /deliveries/{delivery_id}`
 
 Safety: **read** · Authentication: **required**
 
-Includes the generated files when the generation succeeded.
+Returns the configured repository or hosted MCP Delivery for a Target. A Delivery in another organization returns 404 not_found.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<generation_id>` | path | `string` | yes | — |
+| `<delivery_id>` | path | `string` | yes | — |
 
 ```sh
-typeship generations retrieve gen_7h2p5d9c3m8w1k6q
+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 generations retrieve --json`.
+Read the full command contract with `typeship docs deliveries get --json`.
+
+## publications
 
-### `typeship generations retrieve-file <generation_id> [flags]`
+### `typeship publications list [flags]`
 
-Fetch one file from a generation
+List publications
 
-`GET /generations/{generation_id}/file`
+`GET /publications`
 
 Safety: **read** · Authentication: **required**
 
-Raw file content, for generations whose target was too large to inline (files_omitted true). The generation's files_index lists valid paths.
+| 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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
+| `--release-id` | query | `string` | no | Only publications of this release. |
+
+```sh
+typeship publications 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 publications list --json`.
+
+### `typeship publications get <publication_id> [flags]`
+
+Get publishing status
+
+`GET /publications/{publication_id}`
+
+Safety: **read** · Authentication: **required**
+
+Returns the registry publishing status for a release. A status in another organization returns 404 not_found.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<generation_id>` | path | `string` | yes | — |
-| `--path` | query | `string` | yes | Repo-relative path inside the generated package. |
+| `<publication_id>` | path | `string` | yes | — |
 
 ```sh
-typeship generations retrieve-file gen_7h2p5d9c3m8w1k6q --path openapi.yaml
+typeship publications get pub_2m8q4v7k1p9d5h6c
 ```
 
 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 retrieve-file --json`.
+Read the full command contract with `typeship docs publications get --json`.
 
-## definitionRevisions
+## generations
 
-### `typeship definition-revisions list <definition_id> [flags]`
+### `typeship generations list [flags]`
 
-List Definition Revisions
+List generations
 
-`GET /definitions/{definition_id}/revisions`
+`GET /generations`
 
 Safety: **read** · Authentication: **required**
 
-Immutable snapshots of the complete resolved document graph this Definition observed, newest first. Content is available from the revision and document endpoints and is never embedded in a list response.
-
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<definition_id>` | path | `string` | yes | — |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. 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 definition-revisions list def_2p8m4q7k1v9d6h3c
+typeship generations 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 definition-revisions list --json`.
+Read the full command contract with `typeship docs generations list --json`.
 
-### `typeship definition-revisions retrieve <definition_revision_id> [flags]`
+### `typeship generations get <generation_id> [flags]`
 
-Retrieve a Definition Revision
+Get a generation
 
-`GET /definition_revisions/{definition_revision_id}`
+`GET /generations/{generation_id}`
 
 Safety: **read** · Authentication: **required**
 
-Metadata for one immutable resolved document graph. Fetch its canonical content or individual source documents from the content endpoints.
+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 |
 | --- | --- | --- | --- | --- |
-| `<definition_revision_id>` | path | `string` | yes | — |
+| `<generation_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via generations_list). IDs come from generations_list. |
 
 ```sh
-typeship definition-revisions retrieve drev_6m1q8v4k2p9d7h3c
+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 definition-revisions retrieve --json`.
+Read the full command contract with `typeship docs generations get --json`.
 
-### `typeship definition-revisions retrieve-content <definition_revision_id> [flags]`
+### `typeship generations list-files <generation_id> [flags]`
 
-Retrieve a Definition Revision's canonical content
+List a Generation's files
 
-`GET /definition_revisions/{definition_revision_id}/content`
+`GET /generations/{generation_id}/files`
 
 Safety: **read** · Authentication: **required**
 
-Returns the exact canonical resolved content identified by the revision's graph digest, suitable for saving or piping into a diff.
+Lists the generated package's files, ordered by path. Read content with getFile.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<definition_revision_id>` | path | `string` | yes | — |
+| `<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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
-typeship definition-revisions retrieve-content drev_6m1q8v4k2p9d7h3c
+typeship generations list-files gen_7h2p5d9c3m8w1k6q
 ```
 
-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 generations list-files --json`.
 
-Read the full command contract with `typeship docs definition-revisions retrieve-content --json`.
+## files
 
-### `typeship definition-revisions retrieve-document-content <definition_revision_id> <document_id> [flags]`
+### `typeship files get <file_id> [flags]`
 
-Retrieve one source document from a Definition Revision
+Get a file
 
-`GET /definition_revisions/{definition_revision_id}/documents/{document_id}/content`
+`GET /files/{file_id}`
 
 Safety: **read** · Authentication: **required**
 
+Returns one bounded chunk of an immutable file: at most 24 KiB, as UTF-8 text or, for binary bytes, base64. When next_cursor is not null, repeat the request with cursor and concatenate the chunks in order. A file ID always returns the same bytes.
+
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<definition_revision_id>` | path | `string` | yes | — |
-| `<document_id>` | path | `string` | yes | — |
+| `<file_id>` | path | `string` | yes | — |
+| `--cursor` | query | `string` | no | next_cursor from the preceding chunk of this file. |
 
 ```sh
-typeship definition-revisions retrieve-document-content drev_6m1q8v4k2p9d7h3c doc_8q2m5v1k9p4d7h3c
+typeship files get file_4k8m2v7q1p9d5h6c
 ```
 
 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 definition-revisions retrieve-document-content --json`.
+Read the full command contract with `typeship docs files get --json`.
 
-## account
+## organization
 
-### `typeship account retrieve [flags]`
+### `typeship organization get [flags]`
 
-The account behind the presented credentials
+The organization behind the presented credentials
 
-`GET /me`
+`GET /organization`
 
 Safety: **read** · Authentication: **required**
 
-Returns the account that owns the presented API key. This is also the
-identity endpoint the generated typeship CLI's `whoami` calls.
+Returns the organization associated with your credential. The Typeship CLI uses this endpoint for `whoami`.
 
 ```sh
-typeship account retrieve
+typeship organization get
 ```
 
 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 account retrieve --json`.
+Read the full command contract with `typeship docs organization get --json`.
 
 ## apiKeys
 
@@ -799,16 +1003,16 @@ Read the full command contract with `typeship docs account retrieve --json`.
 
 List API keys
 
-`GET /api_keys`
+`GET /api-keys`
 
 Safety: **read** · Authentication: **required**
 
-Keys are never returned in full — only their identity and last four. Creation stays in the console deliberately: a leaked key that can mint more keys is a leaked account.
+Lists key metadata and the last four characters of each key. Full keys are not returned. Create keys in the Console.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--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 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. 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, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
 typeship api-keys list
@@ -818,22 +1022,48 @@ Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` co
 
 Read the full command contract with `typeship docs api-keys list --json`.
 
+### `typeship api-keys get <api_key_id> [flags]`
+
+Get an API key
+
+`GET /api-keys/{api_key_id}`
+
+Safety: **read** · Authentication: **required**
+
+Returns the key summary and its ETag for conditional revocation.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<api_key_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via api_keys_list). IDs come from api_keys_list. |
+
+```sh
+typeship api-keys get apikey_2nY8mR6pQ4vK9cH3
+```
+
+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 api-keys get --json`.
+
 ### `typeship api-keys revoke <api_key_id> [flags]`
 
 Revoke an API key
 
-`DELETE /api_keys/{api_key_id}`
+`DELETE /api-keys/{api_key_id}`
 
 Safety: **destructive** · Authentication: **required**
 
-Idempotent: revoking an already-revoked key returns the same body, so a rotation script that re-runs does not have to special-case having already succeeded. An OAuth member may revoke a key they created; an organization admin may revoke any key. Organization API keys retain account-wide authority.
+Revokes a key. 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.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<api_key_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via api_keys_list). IDs come from api_keys_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 api-keys revoke api_key_123 --force
+typeship api-keys revoke apikey_2nY8mR6pQ4vK9cH3 --force
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.