@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.3

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]
+tailor 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]
+tailor generate [options]
 ```
 
-<!-- politty:command:generate:usage:end -->
-
-<!-- politty:command:generate:options:start -->
-
 **Options**
 
 | Option              | Alias | Description                                    | Required | Default              |
@@ -81,63 +43,46 @@ 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.
 
-<!-- politty:command:deploy:description:end -->
-
-<!-- politty:command:deploy:usage:start -->
-
 **Usage**
 
 ```
-tailor-sdk deploy [options]
+tailor deploy [options]
 ```
 
-<!-- politty:command:deploy:usage:end -->
-
-<!-- politty:command:deploy:options:start -->
-
 **Options**
 
-| Option                          | Alias | Description                                                       | Required | Default              | Env                               |
-| ------------------------------- | ----- | ----------------------------------------------------------------- | -------- | -------------------- | --------------------------------- |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
-| `--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` |
-| `--yes`                         | `-y`  | Skip confirmation prompts                                         | No       | `false`              | -                                 |
-| `--dry-run`                     | `-d`  | Run the command without making any changes                        | No       | -                    | -                                 |
-| `--no-schema-check`             | -     | Skip schema diff check against migration snapshots                | No       | -                    | -                                 |
-| `--no-validate`                 | -     | Skip client-side validation against platform resource constraints | No       | -                    | -                                 |
-| `--no-cache`                    | -     | Disable bundle caching for this run                               | No       | -                    | -                                 |
-| `--clean-cache`                 | -     | Clean the bundle cache before building                            | No       | -                    | -                                 |
+| Option                          | Alias | Description                                                                          | Required | Default              | Env                               |
+| ------------------------------- | ----- | ------------------------------------------------------------------------------------ | -------- | -------------------- | --------------------------------- |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                         | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                    | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
+| `--config <CONFIG>`             | `-c`  | Path to SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
+| `--yes`                         | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
+| `--dry-run`                     | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
+| `--no-schema-check`             | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
+| `--no-validate`                 | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
+| `--no-cache`                    | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
+| `--clean-cache`                 | -     | Clean the bundle cache before building                                               | No       | -                    | -                                 |
 
-<!-- politty:command:deploy:options:end -->
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+**Config File Modification:**
 
-<!-- politty:command:deploy:global-options-link:start -->
+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.
 
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+**Multiple Config Deploys:**
 
-<!-- politty:command:deploy:global-options-link:end -->
+To deploy interdependent applications to the same workspace in one run, pass comma-separated config paths:
 
-**Config File Modification:**
+```bash
+tailor deploy --config apps/buyer/tailor.config.ts,apps/supplier/tailor.config.ts
+```
 
-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.
+When multiple configs are provided, `deploy` creates or updates all configured services first, then updates the applications. This lets one application reference resources owned by another config with `external: true` during the same deploy.
 
 **Migration Handling:**
 
@@ -173,219 +118,171 @@ 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.
+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`:
 
-<!-- politty:command:remove:heading:start -->
+```bash
+tailor deploy --dry-run > plan.txt
+```
 
-## remove
+In apply mode, the plan is printed to stderr so it does not interfere with piped output.
 
-<!-- politty:command:remove:heading:end -->
+**JSON Output:**
 
-<!-- politty:command:remove:description:start -->
+Pass the global `--json` / `-j` flag to get machine-readable output.
 
-Remove all resources managed by the application from the workspace.
+**Dry-run** (`--dry-run --json`): writes a JSON object to stdout:
 
-<!-- politty:command:remove:description:end -->
+```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" }]
+}
+```
 
-<!-- politty:command:remove:usage:start -->
+- `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.
 
-**Usage**
+**Apply** (`--json`): writes a JSON object to stdout:
 
-```
-tailor-sdk remove [options]
+```json
+{ "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0 }, "status": "applied" }
 ```
 
-<!-- politty:command:remove:usage:end -->
+## remove
 
-<!-- politty:command:remove:options:start -->
+Remove all resources managed by the application from the workspace.
 
-**Options**
+**Usage**
 
-| Option                          | Alias | Description               | Required | Default              | Env                               |
-| ------------------------------- | ----- | ------------------------- | -------- | -------------------- | --------------------------------- |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
-| `--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` |
-| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false`              | -                                 |
+```
+tailor remove [options]
+```
 
-<!-- politty:command:remove:options:end -->
+**Options**
 
-<!-- politty:command:remove:global-options-link:start -->
+| Option                          | Alias | Description                | Required | Default              | Env                            |
+| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
+| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
+| `--yes`                         | `-y`  | Skip confirmation prompts  | No       | `false`              | -                              |
 
 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]
+tailor show [options]
 ```
 
-<!-- politty:command:show:usage:end -->
-
-<!-- politty:command:show:options:start -->
-
 **Options**
 
-| Option                          | Alias | Description             | Required | Default              | Env                               |
-| ------------------------------- | ----- | ----------------------- | -------- | -------------------- | --------------------------------- |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID            | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
-| `--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 -->
+| Option                          | Alias | Description                | Required | Default              | Env                            |
+| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
+| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
 
 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]
+tailor open [options]
 ```
 
-<!-- politty:command:open:usage:end -->
-
-<!-- politty:command:open:options:start -->
-
 **Options**
 
-| Option                          | Alias | Description             | Required | Default              | Env                               |
-| ------------------------------- | ----- | ----------------------- | -------- | -------------------- | --------------------------------- |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID            | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
-| `--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 -->
+| Option                          | Alias | Description                | Required | Default              | Env                            |
+| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
+| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
 
 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>
+tailor 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                               |
-| ------------------------------- | ----- | --------------------------------------------------------------------------------- | -------- | -------------------- | --------------------------------- |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
-| `--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` |
-| `--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 -->
+| Option                          | Alias | Description                                                                       | Required | Default              | Env                            |
+| ------------------------------- | ----- | --------------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                 | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
+| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                        | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
+| `--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       | -                    | -                              |
 
 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**
 
 **Call an endpoint; workspaceId is auto-injected.**
 
 ```bash
-$ tailor-sdk api GetApplication -b '{"applicationName":"app-1"}'
+$ tailor api GetApplication -b '{"applicationName":"app-1"}'
 ```
 
 **Same as above, using --field instead of --body.**
 
 ```bash
-$ tailor-sdk api GetApplication -f applicationName=app-1
+$ tailor api GetApplication -f applicationName=app-1
 ```
 
 **List all invocable OperatorService methods.**
 
 ```bash
-$ tailor-sdk api list
+$ tailor api list
 ```
 
 **Show the input message tree for an endpoint.**
 
 ```bash
-$ tailor-sdk api inspect GetApplication
+$ tailor 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).
+Use `tailor api list` to enumerate invocable methods and `tailor api inspect <endpoint>` to print an endpoint's input message tree (combine with `--json` for machine-readable output).
 
 The request body is inferred from the target endpoint's request schema, and commonly required fields are auto-injected so they can be omitted from `--body`:
 
@@ -398,103 +295,54 @@ 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>
+tailor 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.**
 
 ```bash
-$ tailor-sdk api inspect GetApplication
+$ tailor api inspect GetApplication
 ```
 
 **Inspect a deeply nested input with `(oneof config)` annotations.**
 
 ```bash
-$ tailor-sdk api inspect CreateExecutorExecutor
+$ tailor 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 -->
+Combine with the global `--json` flag for a machine-readable descriptor. Recursive type references and `oneof` membership are annotated. Use `tailor api list` to discover endpoint names.
 
 ### 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
+tailor 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 -->