@typeship-ax/cli 0.8.0 → 0.9.1

package/api.md

@@ -1,19 +1,25 @@
-# typeship — API reference
+# typeship — CLI reference
 
-API version 1.0.0. Package version 0.8.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 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
@@ -23,32 +29,28 @@ that turns the run into a project once a person signs in. With a key, the free p
 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
-{
-  "definition": {
-    "url": "https://example.com"
-  },
-  "target": {
-    "generator": "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,66 +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. Valid only for the same account, operation, filters, and ordering that issued it. |
-
-Returns: `PagePromise<ProjectSummary>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| `--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 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.
 
-### `client.projects.create(body, params)`
+Read the full command contract with `typeship docs projects list --json`.
+
+### `typeship projects create [flags]`
 
 Create a project
 
 `POST /projects`
 
-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.
-
 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), `UnprocessableEntityError` (422), `RateLimitedError` (429), `InternalServerError` (500)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "name": "example",
-  "definition": {
-    "source": {
-      "kind": "url",
-      "url": "https://example.com"
-    }
-  },
-  "targets": [
-    {
-      "name": "example",
-      "generator": "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}`.
 
-### `client.projects.retrieve(projectId)`
+Read the full command contract with `typeship docs projects create --json`.
+
+### `typeship projects retrieve <project_id> [flags]`
 
 Retrieve a project
 
@@ -123,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
 
@@ -149,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 | — |
+| `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 
-Returns: `DeletedProject`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
-
-<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
 
@@ -175,144 +151,118 @@ 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. |
 
-Body: `UpdateProjectRequest` (required)
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
-Returns: `Project`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+```sh
+typeship projects update 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 update --json`.
 
-### `client.projects.retrieveDiagnostics(projectId)`
+### `typeship projects retrieve-diagnostics <project_id> [flags]`
 
 Analyze a project's latest Definition Revision
 
 `GET /projects/{project_id}/diagnostics`
 
-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.
-
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-
-Returns: `DiagnosticReport`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+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.
 
-<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-diagnostics 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-diagnostics --json`.
 
-### `client.projects.refreshDiagnostics(projectId)`
+### `typeship projects refresh-diagnostics <project_id> [flags]`
 
 Refresh a project's Diagnostics from its configured source
 
 `POST /projects/{project_id}/diagnostics`
 
-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: **write** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-
-Returns: `DiagnosticReport`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429)
+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.
 
-<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. |
+| `--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. |
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+```sh
+typeship projects refresh-diagnostics prj_4f8k2m7x9q1v6b3n
 ```
 
-</details>
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-### `client.projects.remediateDiagnostics(projectId, body)`
+Read the full command contract with `typeship docs projects refresh-diagnostics --json`.
+
+### `typeship projects remediate-diagnostics <project_id> [flags]`
 
 Apply exact, reviewed diagnostic remediations
 
 `POST /projects/{project_id}/diagnostics/remediations`
 
-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.
-
 Safety: **write** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-
-Body: `DiagnosticRemediationRequest` (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.
 
-Returns: `DiagnosticRemediation`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429)
+| 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. |
 
-<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
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n",
-  "diagnostic_ids": [
-    "value"
-  ]
-}
+```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}`.
+
+Read the full command contract with `typeship docs projects remediate-diagnostics --json`.
 
-### `client.projects.retrieveIntegrationHealth(projectId)`
+### `typeship projects retrieve-integration-health <project_id> [flags]`
 
 Diagnose a project's repository integrations
 
 `GET /projects/{project_id}/integration-health`
 
-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.
-
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-
-Returns: `RepositoryIntegrationHealth`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+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.
 
-<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-integration-health 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-integration-health --json`.
 
-### `client.projects.listGenerations(projectId, params)`
+### `typeship projects list-generations <project_id> [flags]`
 
 List a project's generations
 
@@ -320,33 +270,29 @@ List a project's generations
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| 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. Valid only for the same account, operation, filters, and ordering that issued it. |
-| `targetId` | query | `TargetId` | no | Only generations for this persisted Target. |
-
-Returns: `PagePromise<Generation>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `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. |
+| `--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. |
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+```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.
+
+Read the full command contract with `typeship docs projects list-generations --json`.
 
-### `client.projects.generate(projectId)`
+### `typeship projects generate <project_id> [flags]`
 
 Generate targets and open pull requests
 
 `POST /projects/{project_id}/generations`
 
+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.
@@ -355,29 +301,22 @@ 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.
 
-Safety: **write** · Authentication: **required**
-
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-
-Returns: `GenerationBatch`
-Errors: `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429), `InternalServerError` (500)
+| `<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. |
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+```sh
+typeship projects generate 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 generate --json`.
 
 ## definitions
 
-### `client.definitions.retrieve(definitionId)`
+### `typeship definitions retrieve <definition_id> [flags]`
 
 Retrieve a Definition
 
@@ -385,57 +324,50 @@ Retrieve a Definition
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `definitionId` | path | `DefinitionId` | yes | — |
-
-Returns: `Definition`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+| `<definition_id>` | path | `string` | yes | — |
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "definition_id": "def_2p8m4q7k1v9d6h3c"
-}
+```sh
+typeship definitions retrieve def_2p8m4q7k1v9d6h3c
 ```
 
-</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 definitions retrieve --json`.
 
-### `client.definitions.update(definitionId, body)`
+### `typeship definitions update <definition_id> [flags]`
 
 Update and resolve a Definition
 
 `PATCH /definitions/{definition_id}`
 
-Resolves the complete document graph and records a new immutable revision before saving.
-
 Safety: **write** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `definitionId` | path | `DefinitionId` | yes | — |
-
-Body: `DefinitionUpdateRequest` (required)
+Resolves the complete document graph and records a new immutable revision before saving.
 
-Returns: `Definition`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429)
+| 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. |
 
-<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
-{
-  "definition_id": "def_2p8m4q7k1v9d6h3c"
-}
+```sh
+typeship definitions update def_2p8m4q7k1v9d6h3c
 ```
 
-</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 definitions update --json`.
 
 ## targets
 
-### `client.targets.list(projectId, params)`
+### `typeship targets list <project_id> [flags]`
 
 List a project's Targets
 
@@ -443,60 +375,55 @@ List a project's Targets
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| 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. Valid only for the same account, operation, filters, and ordering that issued it. |
-
-Returns: `PagePromise<Target>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| `<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. |
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
-}
+```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.
 
-### `client.targets.create(projectId, body)`
+Read the full command contract with `typeship docs targets list --json`.
+
+### `typeship targets create <project_id> [flags]`
 
 Create an independently configured Target
 
 `POST /projects/{project_id}/targets`
 
-Several Targets may use the same generator with distinct configuration, Deliveries, and release streams.
-
 Safety: **write** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
-
-Body: `TargetFields` (required)
-
-Returns: `TargetResponse`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+Several Targets may use the same generator with distinct configuration, Deliveries, and release streams.
 
-```json
-{
-  "project_id": "prj_4f8k2m7x9q1v6b3n",
-  "name": "example",
-  "definition_id": "def_2p8m4q7k1v9d6h3c",
-  "generator": "typescript-sdk"
-}
+| 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
 ```
 
-</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 targets create --json`.
 
-### `client.targets.retrieve(targetId)`
+### `typeship targets retrieve <target_id> [flags]`
 
 Retrieve a Target
 
@@ -504,53 +431,41 @@ Retrieve a Target
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `targetId` | path | `TargetId` | yes | — |
+| `<target_id>` | path | `string` | yes | — |
 
-Returns: `TargetResponse`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "target_id": "tgt_5m8q2v7k1p9d4h6c"
-}
+```sh
+typeship targets retrieve tgt_5m8q2v7k1p9d4h6c
 ```
 
-</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 targets retrieve --json`.
 
-### `client.targets.delete(targetId)`
+### `typeship targets delete <target_id> [flags]`
 
 Delete an unused Target
 
 `DELETE /targets/{target_id}`
 
-Targets with Generation or release history, or an active release candidate, must be disabled instead.
-
 Safety: **destructive** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `targetId` | path | `TargetId` | yes | — |
-
-Returns: `DeletedTarget`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitedError` (429)
+Targets with Generation or release history, or an active release candidate, must be disabled instead.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | — |
 
-```json
-{
-  "target_id": "tgt_5m8q2v7k1p9d4h6c"
-}
+```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}`.
+
+Read the full command contract with `typeship docs targets delete --json`.
 
-### `client.targets.update(targetId, body)`
+### `typeship targets update <target_id> [flags]`
 
 Update a Target, its Deliveries, or its next reviewed version
 
@@ -558,27 +473,28 @@ Update a Target, its Deliveries, or its next reviewed version
 
 Safety: **write** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `targetId` | path | `TargetId` | yes | — |
-
-Body: `TargetUpdateRequest` (required)
-
-Returns: `TargetResponse`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "target_id": "tgt_5m8q2v7k1p9d4h6c"
-}
+| `<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
 ```
 
-</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 targets update --json`.
 
-### `client.targets.listReleases(targetId, params)`
+### `typeship targets list-releases <target_id> [flags]`
 
 List immutable releases for a Target
 
@@ -586,27 +502,21 @@ List immutable releases for a Target
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `targetId` | path | `TargetId` | yes | — |
-| `limit` | query | `number` | no | Maximum number of resources to return. |
-| `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: `PagePromise<TargetRelease>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+| `<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. |
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "target_id": "tgt_5m8q2v7k1p9d4h6c"
-}
+```sh
+typeship targets list-releases tgt_5m8q2v7k1p9d4h6c
 ```
 
-</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 targets list-releases --json`.
 
-### `client.targets.retrieveRelease(targetReleaseId)`
+### `typeship targets retrieve-release <target_release_id> [flags]`
 
 Retrieve an immutable Target release
 
@@ -614,173 +524,136 @@ Retrieve an immutable Target release
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `targetReleaseId` | path | `TargetReleaseId` | yes | — |
+| `<target_release_id>` | path | `string` | yes | — |
 
-Returns: `TargetReleaseResponse`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
-
-```json
-{
-  "target_release_id": "rel_7m2q8v4k1p9d5h6c"
-}
+```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}`.
+
+Read the full command contract with `typeship docs targets retrieve-release --json`.
 
 ## generations
 
-### `client.generations.retrieve(generationId)`
+### `typeship generations retrieve <generation_id> [flags]`
 
 Retrieve a generation
 
 `GET /generations/{generation_id}`
 
-Includes the generated files when the generation succeeded.
-
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `generationId` | path | `GenerationId` | yes | — |
-
-Returns: `GenerationResponse`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+Includes the generated files when the generation succeeded.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<generation_id>` | path | `string` | yes | — |
 
-```json
-{
-  "generation_id": "gen_7h2p5d9c3m8w1k6q"
-}
+```sh
+typeship generations retrieve gen_7h2p5d9c3m8w1k6q
 ```
 
-</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 generations retrieve --json`.
+
+### `typeship generations retrieve-file <generation_id> [flags]`
 
 Fetch one file from a generation
 
 `GET /generations/{generation_id}/file`
 
-Raw file content, for generations whose target was too large to inline (files_omitted true). The generation's files_index lists valid paths.
-
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `generationId` | path | `GenerationId` | yes | — |
-| `path` | query | `string` | yes | Repo-relative path inside the generated package. |
-
-Returns: `string`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+Raw file content, for generations whose target was too large to inline (files_omitted true). The generation's files_index lists valid paths.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<generation_id>` | path | `string` | yes | — |
+| `--path` | query | `string` | yes | Repo-relative path inside the generated package. |
 
-```json
-{
-  "generation_id": "gen_7h2p5d9c3m8w1k6q",
-  "path": "openapi.yaml"
-}
+```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`.
 
 ## definitionRevisions
 
-### `client.definitionRevisions.list(definitionId, params)`
+### `typeship definition-revisions list <definition_id> [flags]`
 
 List Definition Revisions
 
 `GET /definitions/{definition_id}/revisions`
 
-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.
-
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `definitionId` | path | `DefinitionId` | yes | — |
-| `limit` | query | `number` | no | Maximum number of resources to return. |
-| `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: `PagePromise<DefinitionRevision>` — auto-paginating (`for await` walks every page)
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+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.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| 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. |
 
-```json
-{
-  "definition_id": "def_2p8m4q7k1v9d6h3c"
-}
+```sh
+typeship definition-revisions list def_2p8m4q7k1v9d6h3c
 ```
 
-</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 definition-revisions list --json`.
 
-### `client.definitionRevisions.retrieve(definitionRevisionId)`
+### `typeship definition-revisions retrieve <definition_revision_id> [flags]`
 
 Retrieve a Definition Revision
 
 `GET /definition_revisions/{definition_revision_id}`
 
-Metadata for one immutable resolved document graph. Fetch its canonical content or individual source documents from the content endpoints.
-
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `definitionRevisionId` | path | `DefinitionRevisionId` | yes | — |
-
-Returns: `DefinitionRevisionResponse`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+Metadata for one immutable resolved document graph. Fetch its canonical content or individual source documents from the content endpoints.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<definition_revision_id>` | path | `string` | yes | — |
 
-```json
-{
-  "definition_revision_id": "drev_6m1q8v4k2p9d7h3c"
-}
+```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.definitionRevisions.retrieveContent(definitionRevisionId)`
+Read the full command contract with `typeship docs definition-revisions retrieve --json`.
+
+### `typeship definition-revisions retrieve-content <definition_revision_id> [flags]`
 
 Retrieve a Definition Revision's canonical content
 
 `GET /definition_revisions/{definition_revision_id}/content`
 
-Returns the exact canonical resolved content identified by the revision's graph digest, suitable for saving or piping into a diff.
-
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `definitionRevisionId` | path | `DefinitionRevisionId` | yes | — |
-
-Returns: `string`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+Returns the exact canonical resolved content identified by the revision's graph digest, suitable for saving or piping into a diff.
 
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<definition_revision_id>` | path | `string` | yes | — |
 
-```json
-{
-  "definition_revision_id": "drev_6m1q8v4k2p9d7h3c"
-}
+```sh
+typeship definition-revisions retrieve-content drev_6m1q8v4k2p9d7h3c
 ```
 
-</details>
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
-### `client.definitionRevisions.retrieveDocumentContent(definitionRevisionId, documentId)`
+Read the full command contract with `typeship docs definition-revisions retrieve-content --json`.
+
+### `typeship definition-revisions retrieve-document-content <definition_revision_id> <document_id> [flags]`
 
 Retrieve one source document from a Definition Revision
 
@@ -788,104 +661,83 @@ Retrieve one source document from a Definition Revision
 
 Safety: **read** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
+| Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `definitionRevisionId` | path | `DefinitionRevisionId` | yes | — |
-| `documentId` | path | `DefinitionDocumentId` | yes | — |
-
-Returns: `string`
-Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
-
-<details>
-<summary>Wire arguments (CLI and MCP)</summary>
+| `<definition_revision_id>` | path | `string` | yes | — |
+| `<document_id>` | path | `string` | yes | — |
 
-```json
-{
-  "definition_revision_id": "drev_6m1q8v4k2p9d7h3c",
-  "document_id": "doc_8q2m5v1k9p4d7h3c"
-}
+```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. Valid only for the same account, operation, filters, and ordering that issued it. |
-
-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.
+
+Read the full command contract with `typeship docs api-keys list --json`.
 
-### `client.apiKeys.revoke(apiKeyId)`
+### `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. An OAuth member may revoke a key they created; an organization admin may revoke any key. Organization API keys retain account-wide authority.
-
 Safety: **destructive** · Authentication: **required**
 
-| Parameter | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `apiKeyId` | path | `string` | yes | — |
-
-Returns: `ApiKeyResponse`
-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`.