@tailor-platform/sdk 1.68.0 → 1.70.0

package/docs/cli/application.md

@@ -2,78 +2,40 @@
 
 Commands for managing Tailor Platform applications. These commands work with `tailor.config.ts`.
 
-<!-- politty:command:init:heading:start -->
-
 ## init
 
-<!-- politty:command:init:heading:end -->
-
-<!-- politty:command:init:description:start -->
-
 Initialize a new project using create-sdk.
 
-<!-- politty:command:init:description:end -->
-
-<!-- politty:command:init:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk init [options] [name]
 ```
 
-<!-- politty:command:init:usage:end -->
-
-<!-- politty:command:init:arguments:start -->
-
 **Arguments**
 
 | Argument | Description  | Required |
 | -------- | ------------ | -------- |
 | `name`   | Project name | No       |
 
-<!-- politty:command:init:arguments:end -->
-
-<!-- politty:command:init:options:start -->
-
 **Options**
 
 | Option                  | Alias | Description   | Required | Default |
 | ----------------------- | ----- | ------------- | -------- | ------- |
 | `--template <TEMPLATE>` | `-t`  | Template name | No       | -       |
 
-<!-- politty:command:init:options:end -->
-
-<!-- politty:command:init:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:init:global-options-link:end -->
-
-<!-- politty:command:generate:heading:start -->
-
 ## generate
 
-<!-- politty:command:generate:heading:end -->
-
-<!-- politty:command:generate:description:start -->
-
 Generate files using Tailor configuration.
 
-<!-- politty:command:generate:description:end -->
-
-<!-- politty:command:generate:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk generate [options]
 ```
 
-<!-- politty:command:generate:usage:end -->
-
-<!-- politty:command:generate:options:start -->
-
 **Options**
 
 | Option              | Alias | Description                                    | Required | Default              |
@@ -81,40 +43,20 @@ tailor-sdk generate [options]
 | `--config <CONFIG>` | `-c`  | Path to SDK config file                        | No       | `"tailor.config.ts"` |
 | `--watch`           | `-W`  | Watch for type/resolver changes and regenerate | No       | `false`              |
 
-<!-- politty:command:generate:options:end -->
-
-<!-- politty:command:generate:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:generate:global-options-link:end -->
-
-<!-- politty:command:deploy:heading:start -->
-
 ## deploy
 
-<!-- politty:command:deploy:heading:end -->
-
-<!-- politty:command:deploy:description:start -->
-
 Deploy your application by applying the Tailor configuration.
 
 **Aliases:** `apply`
 
-<!-- politty:command:deploy:description:end -->
-
-<!-- politty:command:deploy:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk deploy [options]
 ```
 
-<!-- politty:command:deploy:usage:end -->
-
-<!-- politty:command:deploy:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                                       | Required | Default              | Env                               |
@@ -129,14 +71,7 @@ tailor-sdk deploy [options]
 | `--no-cache`                    | -     | Disable bundle caching for this run                               | No       | -                    | -                                 |
 | `--clean-cache`                 | -     | Clean the bundle cache before building                            | No       | -                    | -                                 |
 
-<!-- politty:command:deploy:options:end -->
-
-<!-- politty:command:deploy:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-<!-- politty:command:deploy:global-options-link:end -->
-
 **Config File Modification:**
 
 On first run, `deploy` automatically injects a stable `id: "<uuid>"` field into your `defineConfig({...})` call in `tailor.config.ts`. This UUID is used to track your application across renames so the SDK can recognize ownership across renames. Commit the generated id to version control. See [Configuration](../configuration.md#application-settings) for details.
@@ -175,24 +110,49 @@ Before applying changes, `deploy` shows a preview of the planned resource change
 After the detailed list, a summary line is printed:
 
 ```text
-Plan: 5 to create, 3 to update, 1 to delete, 25 unchanged
+Plan: 5 to create, 3 to update, 1 to delete
+```
+
+Use `--dry-run` to preview the plan without applying anything. In dry-run mode the plan is written to **stdout**, so it can be captured in CI without `2>&1`:
+
+```bash
+tailor-sdk deploy --dry-run > plan.txt
 ```
 
-Use `--dry-run` to preview the plan without applying anything.
+In apply mode, the plan is printed to stderr so it does not interfere with piped output.
 
-<!-- politty:command:remove:heading:start -->
+**JSON Output:**
 
-## remove
+Pass the global `--json` / `-j` flag to get machine-readable output.
 
-<!-- politty:command:remove:heading:end -->
+**Dry-run** (`--dry-run --json`): writes a JSON object to stdout:
 
-<!-- politty:command:remove:description:start -->
+```json
+{
+  "summary": { "create": 2, "update": 1, "delete": 0, "replace": 0 },
+  "changes": [{ "action": "create", "name": "Order", "labels": ["type"], "namespace": "tailordb" }],
+  "warnings": [
+    { "type": "unmanaged", "resourceType": "tailorDB", "name": "LegacyType" },
+    { "type": "skippedSecret", "resourceType": "secret", "name": "DB_PASSWORD" }
+  ],
+  "conflicts": [{ "resourceType": "tailorDB", "name": "User", "currentOwner": "other-app" }]
+}
+```
 
-Remove all resources managed by the application from the workspace.
+- `summary` — counts of each change type.
+- `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`.
+- `warnings` — resources not in config (`type: "unmanaged"`) or secrets with missing values (`type: "skippedSecret"`). Unmanaged resources require confirmation in apply mode (apply is cancelled if declined); skipped secrets are non-blocking.
+- `conflicts` — resources owned by another application that conflict with the current config. Require confirmation in apply mode; apply is cancelled if declined.
 
-<!-- politty:command:remove:description:end -->
+**Apply** (`--json`): writes a JSON object to stdout:
 
-<!-- politty:command:remove:usage:start -->
+```json
+{ "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0 }, "status": "applied" }
+```
+
+## remove
+
+Remove all resources managed by the application from the workspace.
 
 **Usage**
 
@@ -200,10 +160,6 @@ Remove all resources managed by the application from the workspace.
 tailor-sdk remove [options]
 ```
 
-<!-- politty:command:remove:usage:end -->
-
-<!-- politty:command:remove:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description               | Required | Default              | Env                               |
@@ -213,38 +169,18 @@ tailor-sdk remove [options]
 | `--config <CONFIG>`             | `-c`  | Path to SDK config file   | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
 | `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false`              | -                                 |
 
-<!-- politty:command:remove:options:end -->
-
-<!-- politty:command:remove:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:remove:global-options-link:end -->
-
-<!-- politty:command:show:heading:start -->
-
 ## show
 
-<!-- politty:command:show:heading:end -->
-
-<!-- politty:command:show:description:start -->
-
 Show information about the deployed application.
 
-<!-- politty:command:show:description:end -->
-
-<!-- politty:command:show:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk show [options]
 ```
 
-<!-- politty:command:show:usage:end -->
-
-<!-- politty:command:show:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description             | Required | Default              | Env                               |
@@ -253,38 +189,18 @@ tailor-sdk show [options]
 | `--profile <PROFILE>`           | `-p`  | Workspace profile       | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
 | `--config <CONFIG>`             | `-c`  | Path to SDK config file | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
 
-<!-- politty:command:show:options:end -->
-
-<!-- politty:command:show:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:show:global-options-link:end -->
-
-<!-- politty:command:open:heading:start -->
-
 ## open
 
-<!-- politty:command:open:heading:end -->
-
-<!-- politty:command:open:description:start -->
-
 Open Tailor Platform Console.
 
-<!-- politty:command:open:description:end -->
-
-<!-- politty:command:open:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk open [options]
 ```
 
-<!-- politty:command:open:usage:end -->
-
-<!-- politty:command:open:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description             | Required | Default              | Env                               |
@@ -293,48 +209,24 @@ tailor-sdk open [options]
 | `--profile <PROFILE>`           | `-p`  | Workspace profile       | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
 | `--config <CONFIG>`             | `-c`  | Path to SDK config file | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
 
-<!-- politty:command:open:options:end -->
-
-<!-- politty:command:open:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:open:global-options-link:end -->
-
-<!-- politty:command:api:heading:start -->
-
 ## api
 
-<!-- politty:command:api:heading:end -->
-
-<!-- politty:command:api:description:start -->
-
 Call Tailor Platform API endpoints directly.
 
-<!-- politty:command:api:description:end -->
-
-<!-- politty:command:api:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk api [options] [command] <endpoint>
 ```
 
-<!-- politty:command:api:usage:end -->
-
-<!-- politty:command:api:arguments:start -->
-
 **Arguments**
 
 | Argument   | Description                                                                                  | Required |
 | ---------- | -------------------------------------------------------------------------------------------- | -------- |
 | `endpoint` | API endpoint to call (e.g., 'GetApplication' or 'tailor.v1.OperatorService/GetApplication'). | Yes      |
 
-<!-- politty:command:api:arguments:end -->
-
-<!-- politty:command:api:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                                                       | Required | Default              | Env                               |
@@ -345,15 +237,14 @@ tailor-sdk api [options] [command] <endpoint>
 | `--body <BODY>`                 | `-b`  | Request body as JSON.                                                             | No       | `"{}"`               | -                                 |
 | `--field <FIELD>`               | `-f`  | Set a body field as `key=value` (repeatable; dotted keys nest). Overrides --body. | No       | -                    | -                                 |
 
-<!-- politty:command:api:options:end -->
-
-<!-- politty:command:api:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:api:global-options-link:end -->
+**Commands**
 
-<!-- politty:command:api:examples:start -->
+| Command                       | Description                                                  |
+| ----------------------------- | ------------------------------------------------------------ |
+| [`api list`](#api-list)       | List all invocable OperatorService methods.                  |
+| [`api inspect`](#api-inspect) | Print the input message tree of an OperatorService endpoint. |
 
 **Examples**
 
@@ -381,10 +272,6 @@ $ tailor-sdk api list
 $ tailor-sdk api inspect GetApplication
 ```
 
-<!-- politty:command:api:examples:end -->
-
-<!-- politty:command:api:notes:start -->
-
 **Notes**
 
 Use `tailor-sdk api list` to enumerate invocable methods and `tailor-sdk api inspect <endpoint>` to print an endpoint's input message tree (combine with `--json` for machine-readable output).
@@ -400,47 +287,24 @@ Values already present in `--body` are never overridden. If a value cannot be re
 
 Use `--field key=value` (repeatable) to set request body fields without writing JSON. Dotted keys (e.g. `application.name=foo`) build nested objects. `--field` overrides matching fields in `--body` and tab-completes from the endpoint's request schema.
 
-<!-- politty:command:api:notes:end -->
-<!-- politty:command:api inspect:heading:start -->
-
 ### api inspect
 
-<!-- politty:command:api inspect:heading:end -->
-
-<!-- politty:command:api inspect:description:start -->
-
 Print the input message tree of an OperatorService endpoint.
 
-<!-- politty:command:api inspect:description:end -->
-
-<!-- politty:command:api inspect:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk api inspect <endpoint>
 ```
 
-<!-- politty:command:api inspect:usage:end -->
-
-<!-- politty:command:api inspect:arguments:start -->
-
 **Arguments**
 
 | Argument   | Description                                                                                     | Required |
 | ---------- | ----------------------------------------------------------------------------------------------- | -------- |
 | `endpoint` | API endpoint to inspect (e.g., 'GetApplication' or 'tailor.v1.OperatorService/GetApplication'). | Yes      |
 
-<!-- politty:command:api inspect:arguments:end -->
-
-<!-- politty:command:api inspect:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:api inspect:global-options-link:end -->
-
-<!-- politty:command:api inspect:examples:start -->
-
 **Examples**
 
 **Show fields of GetApplicationRequest.**
@@ -455,48 +319,22 @@ $ tailor-sdk api inspect GetApplication
 $ tailor-sdk api inspect CreateExecutorExecutor
 ```
 
-<!-- politty:command:api inspect:examples:end -->
-
-<!-- politty:command:api inspect:notes:start -->
-
 **Notes**
 
 Combine with the global `--json` flag for a machine-readable descriptor. Recursive type references and `oneof` membership are annotated. Use `tailor-sdk api list` to discover endpoint names.
 
-<!-- politty:command:api inspect:notes:end -->
-
-<!-- politty:command:api list:heading:start -->
-
 ### api list
 
-<!-- politty:command:api list:heading:end -->
-
-<!-- politty:command:api list:description:start -->
-
 List all invocable OperatorService methods.
 
-<!-- politty:command:api list:description:end -->
-
-<!-- politty:command:api list:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk api list
 ```
 
-<!-- politty:command:api list:usage:end -->
-
-<!-- politty:command:api list:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:api list:global-options-link:end -->
-
-<!-- politty:command:api list:notes:start -->
-
 **Notes**
 
 Only single-request (non-streaming) methods are listed, because the CLI issues a single JSON request and reads one JSON response.
-
-<!-- politty:command:api list:notes:end -->