@typeship-ax/cli 0.6.0 → 0.9.1

package/api.md

@@ -1,54 +1,56 @@
-# typeship — API reference
+# typeship — CLI reference
 
-Version 0.6.0. Generated by typeship; regenerate rather than editing.
+API version 1.0.0. Package version 0.9.1. Generated by typeship; regenerate rather than editing.
 
-All methods return `ApiResult<T, E>`: check `result.ok`, or `unwrap(result)` to throw typed errors.
+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.
 
-For complete input and output schemas, use [`api.json`](./api.json), the machine-readable companion to this reference. Collapsed wire arguments below use API field names for CLI and MCP; SDK calls use the native signature shown in each heading.
+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.
+
+Use `--fields id,name` to project response fields. `--base-url <url>` overrides the endpoint. See [`README.md`](./README.md) for local setup and authentication.
+
+For complete input and output schemas, use [`api.json`](./api.json), the machine-readable companion to this reference.
 
 ## generate
 
-### `client.generate.run(body)`
+### `typeship generate run [flags]`
 
-Generate a package from a spec
+Generate one Target from a Definition
 
 `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 spec URL also carry `claim.url`, a link
+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 whole spec. A present but invalid key is a
+paid plans generate the complete Definition. A present but invalid key is a
 401, not a downgrade to anonymous.
 
-Safety: **write** · Authentication: **optional**
-
-Body: `GenerateRequest` (required)
-
-Returns: `GenerationResult`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `PayloadTooLargeError` (413), `UnprocessableEntityError` (422), `RateLimitedError` (429), `ApiResponseError` (default)
+| 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. |
+| `--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. |
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
-```json
-{
-  "spec": {
-    "url": "https://example.com"
-  },
-  "outputs": [
-    "typescript-sdk"
-  ]
-}
+```sh
+typeship generate run --definition '{"url":"https://example.com"}' --target '{"generator":"typescript-sdk"}'
 ```
 
-</details>
+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`.
 
 ## projects
 
-### `client.projects.list(params)`
+### `typeship projects list [flags]`
 
 List projects
 
@@ -56,61 +58,50 @@ List projects
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `limit` | query | `number` | no | Maximum number of resources to return. |
-| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
-
-Returns: `PagePromise<Project>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
+| `--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. |
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{}
+```sh
+typeship projects list
 ```
 
-</details>
+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 --json`.
 
-### `client.projects.create(body, params)`
+### `typeship projects create [flags]`
 
 Create a project
 
 `POST /projects`
 
-Stores a URL- or GitHub-sourced project. Free includes one stored project, every selected output, 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 the whole spec.
-
 Safety: **write** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+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.
+
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `idempotencyKey` | header | `string` | no | Uniquely identifies this creation attempt. Retrying the same request with the same key returns the original response instead of creating another project. Reusing a key with different parameters returns 409. |
-
-Body: `CreateProjectRequest` (required)
-
-Returns: `Project`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `ConflictError` (409), `RateLimitedError` (429), `InternalServerError` (500)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "name": "example",
-  "source": {
-    "kind": "url",
-    "url": "https://example.com"
-  },
-  "outputs": [
-    "typescript-sdk"
-  ]
-}
+| `--name` | body | `string` | yes | — |
+| `--definition` | 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. |
+
+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"}]'
 ```
 
-</details>
+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`.
 
-### `client.projects.retrieve(projectId)`
+### `typeship projects retrieve <project_id> [flags]`
 
 Retrieve a project
 
@@ -118,25 +109,21 @@ Retrieve a project
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-
-Returns: `Project`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+Returns Project-owned fields only. List Targets separately for Target and Delivery data.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| 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. |
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+```sh
+typeship projects retrieve prj_4f8k2m7x9q1v6b3n
 ```
 
-</details>
+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`.
 
-### `client.projects.delete(projectId)`
+### `typeship projects delete <project_id> [flags]`
 
 Delete a project
 
@@ -144,25 +131,19 @@ Delete a project
 
 Safety: **destructive** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-
-Returns: `DeletedProject`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+| `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+```sh
+typeship projects delete prj_4f8k2m7x9q1v6b3n --force
 ```
 
-</details>
+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`.
 
-### `client.projects.update(projectId, body)`
+### `typeship projects update <project_id> [flags]`
 
 Update a project
 
@@ -170,90 +151,149 @@ Update a project
 
 Safety: **write** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
+| `<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. |
+
+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
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Body: `UpdateProjectRequest` (required)
+Read the full command contract with `typeship docs projects update --json`.
 
-Returns: `Project`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+### `typeship projects retrieve-diagnostics <project_id> [flags]`
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Analyze a project's latest Definition Revision
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+`GET /projects/{project_id}/diagnostics`
+
+Safety: **read** · 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.
+
+| 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-diagnostics prj_4f8k2m7x9q1v6b3n
 ```
 
-</details>
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-### `client.projects.retrieveGithubHealth(projectId)`
+Read the full command contract with `typeship docs projects retrieve-diagnostics --json`.
 
-Diagnose a project's GitHub integration
+### `typeship projects refresh-diagnostics <project_id> [flags]`
 
-`GET /projects/{project_id}/github`
+Refresh a project's Diagnostics from its configured source
 
-Returns machine-actionable source and destination access, spec readability, optional label setup, required status names, and the latest durable webhook delivery. The console renders this same result.
+`POST /projects/{project_id}/diagnostics`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
+
+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.
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
+| `<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. |
+
+```sh
+typeship projects refresh-diagnostics 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 refresh-diagnostics --json`.
 
-Returns: `GithubIntegrationHealth`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+### `typeship projects remediate-diagnostics <project_id> [flags]`
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Apply exact, reviewed diagnostic remediations
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+`POST /projects/{project_id}/diagnostics/remediations`
+
+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.
+
+| 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. |
+
+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"]'
 ```
 
-</details>
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-### `client.projects.listGenerations(projectId, params)`
+Read the full command contract with `typeship docs projects remediate-diagnostics --json`.
 
-List a project's generations
+### `typeship projects retrieve-integration-health <project_id> [flags]`
 
-`GET /projects/{project_id}/generations`
+Diagnose a project's repository integrations
+
+`GET /projects/{project_id}/integration-health`
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+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.
+
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-| `limit` | query | `number` | no | Maximum number of resources to return. |
-| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
-| `output` | query | `OutputId` | no | Only generations for this output. |
+| `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 
-Returns: `PagePromise<Generation>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+```sh
+typeship projects retrieve-integration-health prj_4f8k2m7x9q1v6b3n
+```
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+Read the full command contract with `typeship docs projects retrieve-integration-health --json`.
+
+### `typeship projects list-generations <project_id> [flags]`
+
+List a project's generations
+
+`GET /projects/{project_id}/generations`
+
+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. |
+| `--target-id` | query | `string` | no | Only generations for this persisted Target. |
+
+```sh
+typeship projects list-generations prj_4f8k2m7x9q1v6b3n
 ```
 
-</details>
+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.
 
-### `client.projects.generate(projectId)`
+Read the full command contract with `typeship docs projects list-generations --json`.
 
-Generate outputs and open pull requests
+### `typeship projects generate <project_id> [flags]`
+
+Generate targets and open pull requests
 
 `POST /projects/{project_id}/generations`
 
-Resolves the project's URL or repository source, generates every
+Safety: **write** · 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
@@ -261,252 +301,443 @@ 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.
 
+| 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. |
+
+```sh
+typeship projects generate 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 generate --json`.
+
+## definitions
+
+### `typeship definitions retrieve <definition_id> [flags]`
+
+Retrieve a Definition
+
+`GET /definitions/{definition_id}`
+
+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**
 
-| Parameter | In | Type | Required | Description |
+Resolves the complete document graph and records a new immutable revision before saving.
+
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
+| `<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.
+
+```sh
+typeship definitions update def_2p8m4q7k1v9d6h3c
+```
 
-Returns: `GenerationBatch`
-Errors: `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429), `InternalServerError` (500)
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Read the full command contract with `typeship docs definitions update --json`.
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+## targets
+
+### `typeship targets list <project_id> [flags]`
+
+List a project's Targets
+
+`GET /projects/{project_id}/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. |
+
+```sh
+typeship targets list prj_4f8k2m7x9q1v6b3n
 ```
 
-</details>
+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.
 
-## generations
+Read the full command contract with `typeship docs targets list --json`.
 
-### `client.generations.retrieve(generationId)`
+### `typeship targets create <project_id> [flags]`
 
-Retrieve a generation
+Create an independently configured Target
 
-`GET /generations/{generation_id}`
+`POST /projects/{project_id}/targets`
 
-Includes the generated files when the generation succeeded.
+Safety: **write** · Authentication: **required**
+
+Several Targets may use the same generator with distinct configuration, Deliveries, and release streams.
+
+| 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` | 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". |
+| `--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. |
+| `--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. |
+
+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
+```
+
+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]`
+
+Retrieve a Target
+
+`GET /targets/{target_id}`
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `generationId` | path | `GenerationId` | yes | — |
+| `<target_id>` | path | `string` | yes | — |
+
+```sh
+typeship targets retrieve tgt_5m8q2v7k1p9d4h6c
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-Returns: `Generation`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+Read the full command contract with `typeship docs targets retrieve --json`.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+### `typeship targets delete <target_id> [flags]`
 
-```json
-{
-  "generation_id": "gen_7h2p5d9c3m8w1k6q"
-}
+Delete an unused Target
+
+`DELETE /targets/{target_id}`
+
+Safety: **destructive** · Authentication: **required**
+
+Targets with Generation or release history, or an active release candidate, must be disabled instead.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | — |
+
+```sh
+typeship targets delete tgt_5m8q2v7k1p9d4h6c --force
 ```
 
-</details>
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-### `client.generations.retrieveFile(generationId, params)`
+Read the full command contract with `typeship docs targets delete --json`.
 
-Fetch one file from a generation
+### `typeship targets update <target_id> [flags]`
 
-`GET /generations/{generation_id}/file`
+Update a Target, its Deliveries, or its next reviewed version
+
+`PATCH /targets/{target_id}`
+
+Safety: **write** · Authentication: **required**
 
-Raw file content, for generations whose output was too large to inline (files_omitted true). The generation's files_index lists valid paths.
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | — |
+| `--name` | body | `string` | no | — |
+| `--state` | body | `string` | no | — |
+| `--edition` | 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 | — |
+
+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
+```
+
+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]`
+
+List immutable releases for a Target
+
+`GET /targets/{target_id}/releases`
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `generationId` | path | `GenerationId` | yes | — |
-| `path` | query | `string` | yes | Repo-relative path inside the generated package. |
+| `<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. |
 
-Returns: `string`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+```sh
+typeship targets list-releases tgt_5m8q2v7k1p9d4h6c
+```
+
+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`.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+### `typeship targets retrieve-release <target_release_id> [flags]`
 
-```json
-{
-  "generation_id": "gen_7h2p5d9c3m8w1k6q",
-  "path": "openapi.yaml"
-}
+Retrieve an immutable Target release
+
+`GET /target_releases/{target_release_id}`
+
+Safety: **read** · Authentication: **required**
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_release_id>` | path | `string` | yes | — |
+
+```sh
+typeship targets retrieve-release rel_7m2q8v4k1p9d5h6c
 ```
 
-</details>
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-## specRevisions
+Read the full command contract with `typeship docs targets retrieve-release --json`.
 
-### `client.specRevisions.list(projectId, params)`
+## generations
 
-List specification revisions
+### `typeship generations retrieve <generation_id> [flags]`
 
-`GET /projects/{project_id}/spec_revisions`
+Retrieve a generation
 
-Immutable snapshots of the exact source text this project consumed, newest first. Raw content is available from each revision's content endpoint and is never embedded in a list response.
+`GET /generations/{generation_id}`
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+Includes the generated files when the generation succeeded.
+
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-| `limit` | query | `number` | no | Maximum number of resources to return. |
-| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+| `<generation_id>` | path | `string` | yes | — |
+
+```sh
+typeship generations retrieve 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 generations retrieve --json`.
 
-Returns: `PagePromise<SpecRevision>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+### `typeship generations retrieve-file <generation_id> [flags]`
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Fetch one file from a generation
+
+`GET /generations/{generation_id}/file`
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+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 |
+| --- | --- | --- | --- | --- |
+| `<generation_id>` | path | `string` | yes | — |
+| `--path` | query | `string` | yes | Repo-relative path inside the generated package. |
+
+```sh
+typeship generations retrieve-file gen_7h2p5d9c3m8w1k6q --path openapi.yaml
 ```
 
-</details>
+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`.
 
-### `client.specRevisions.retrieve(specRevisionId)`
+## definitionRevisions
 
-Retrieve a specification revision
+### `typeship definition-revisions list <definition_id> [flags]`
 
-`GET /spec_revisions/{spec_revision_id}`
+List Definition Revisions
 
-Metadata for one immutable source snapshot. Fetch raw source text from the content endpoint so metadata responses stay small and predictable.
+`GET /definitions/{definition_id}/revisions`
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+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 |
 | --- | --- | --- | --- | --- |
-| `specRevisionId` | path | `SpecRevisionId` | yes | — |
+| `<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. |
+
+```sh
+typeship definition-revisions list def_2p8m4q7k1v9d6h3c
+```
+
+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.
 
-Returns: `SpecRevision`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+Read the full command contract with `typeship docs definition-revisions list --json`.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+### `typeship definition-revisions retrieve <definition_revision_id> [flags]`
 
-```json
-{
-  "spec_revision_id": "spec_6m1q8v4k2p9d7h3c"
-}
+Retrieve a Definition Revision
+
+`GET /definition_revisions/{definition_revision_id}`
+
+Safety: **read** · Authentication: **required**
+
+Metadata for one immutable resolved document graph. Fetch its canonical content or individual source documents from the content endpoints.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<definition_revision_id>` | path | `string` | yes | — |
+
+```sh
+typeship definition-revisions retrieve drev_6m1q8v4k2p9d7h3c
 ```
 
-</details>
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-### `client.specRevisions.retrieveContent(specRevisionId)`
+Read the full command contract with `typeship docs definition-revisions retrieve --json`.
 
-Retrieve a specification revision's raw text
+### `typeship definition-revisions retrieve-content <definition_revision_id> [flags]`
 
-`GET /spec_revisions/{spec_revision_id}/content`
+Retrieve a Definition Revision's canonical content
 
-Returns the exact source text identified by the revision's SHA-256 digest, suitable for saving or piping directly into a diff.
+`GET /definition_revisions/{definition_revision_id}/content`
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+Returns the exact canonical resolved content identified by the revision's graph digest, suitable for saving or piping into a diff.
+
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `specRevisionId` | path | `SpecRevisionId` | yes | — |
+| `<definition_revision_id>` | path | `string` | yes | — |
+
+```sh
+typeship definition-revisions retrieve-content drev_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 definition-revisions retrieve-content --json`.
 
-Returns: `string`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+### `typeship definition-revisions retrieve-document-content <definition_revision_id> <document_id> [flags]`
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Retrieve one source document from a Definition Revision
 
-```json
-{
-  "spec_revision_id": "spec_6m1q8v4k2p9d7h3c"
-}
+`GET /definition_revisions/{definition_revision_id}/documents/{document_id}/content`
+
+Safety: **read** · Authentication: **required**
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<definition_revision_id>` | path | `string` | yes | — |
+| `<document_id>` | path | `string` | yes | — |
+
+```sh
+typeship definition-revisions retrieve-document-content drev_6m1q8v4k2p9d7h3c doc_8q2m5v1k9p4d7h3c
 ```
 
-</details>
+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`.
 
 ## account
 
-### `client.account.retrieve()`
+### `typeship account retrieve [flags]`
 
 The account behind the presented credentials
 
 `GET /me`
 
-Returns the account that owns the presented API key. This is also the
-identity endpoint the generated typeship CLI's `whoami` calls.
-
 Safety: **read** · Authentication: **required**
 
-Returns: `Account`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Returns the account that owns the presented API key. This is also the
+identity endpoint the generated typeship CLI's `whoami` calls.
 
-```json
-{}
+```sh
+typeship account retrieve
 ```
 
-</details>
+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`.
 
 ## apiKeys
 
-### `client.apiKeys.list(params)`
+### `typeship api-keys list [flags]`
 
 List API keys
 
 `GET /api_keys`
 
-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.
-
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `limit` | query | `number` | no | Maximum number of resources to return. |
-| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
-
-Returns: `PagePromise<ApiKey>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
+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.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| 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. |
 
-```json
-{}
+```sh
+typeship api-keys list
 ```
 
-</details>
+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.
 
-### `client.apiKeys.revoke(apiKeyId)`
+Read the full command contract with `typeship docs api-keys list --json`.
+
+### `typeship api-keys revoke <api_key_id> [flags]`
 
 Revoke an API key
 
 `DELETE /api_keys/{api_key_id}`
 
-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.
-
 Safety: **destructive** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `apiKeyId` | path | `string` | yes | — |
-
-Returns: `ApiKey`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+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.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| 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. |
 
-```json
-{
-  "api_key_id": "api_key_123"
-}
+```sh
+typeship api-keys revoke api_key_123 --force
 ```
 
-</details>
+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 revoke --json`.