@tailor-platform/sdk 1.67.1 → 1.69.0

package/docs/cli/workflow.md

@@ -2,29 +2,17 @@
 
 Commands for managing workflows and workflow executions.
 
-<!-- politty:command:workflow:heading:start -->
-
 ## workflow
 
-<!-- politty:command:workflow:heading:end -->
-
-<!-- politty:command:workflow:description:start -->
-
 Manage workflows and workflow executions.
 
-<!-- politty:command:workflow:description:end -->
-
-<!-- politty:command:workflow:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk workflow [command]
 ```
 
-<!-- politty:command:workflow:usage:end -->
-
-<!-- politty:command:workflow:subcommands:start -->
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Commands**
 
@@ -33,40 +21,20 @@ tailor-sdk workflow [command]
 | [`workflow list`](#workflow-list)             | List all workflows in the workspace.           |
 | [`workflow get`](#workflow-get)               | Get workflow details.                          |
 | [`workflow start`](#workflow-start)           | Start a workflow execution.                    |
+| [`workflow wait`](#workflow-wait)             | Wait for a workflow execution.                 |
 | [`workflow executions`](#workflow-executions) | List or get workflow executions.               |
 | [`workflow resume`](#workflow-resume)         | Resume a failed or pending workflow execution. |
 
-<!-- politty:command:workflow:subcommands:end -->
-
-<!-- politty:command:workflow:global-options-link:start -->
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-<!-- politty:command:workflow:global-options-link:end -->
-<!-- politty:command:workflow list:heading:start -->
-
 ### workflow list
 
-<!-- politty:command:workflow list:heading:end -->
-
-<!-- politty:command:workflow list:description:start -->
-
 List all workflows in the workspace.
 
-<!-- politty:command:workflow list:description:end -->
-
-<!-- politty:command:workflow list:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk workflow list [options]
 ```
 
-<!-- politty:command:workflow list:usage:end -->
-
-<!-- politty:command:workflow list:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                              | Required | Default  | Env                            |
@@ -76,47 +44,24 @@ tailor-sdk workflow list [options]
 | `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
 | `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |
 
-<!-- politty:command:workflow list:options:end -->
-
-<!-- politty:command:workflow list:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:workflow list:global-options-link:end -->
-<!-- politty:command:workflow get:heading:start -->
-
 ### workflow get
 
-<!-- politty:command:workflow get:heading:end -->
-
-<!-- politty:command:workflow get:description:start -->
-
 Get workflow details.
 
-<!-- politty:command:workflow get:description:end -->
-
-<!-- politty:command:workflow get:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk workflow get [options] <name>
 ```
 
-<!-- politty:command:workflow get:usage:end -->
-
-<!-- politty:command:workflow get:arguments:start -->
-
 **Arguments**
 
 | Argument | Description   | Required |
 | -------- | ------------- | -------- |
 | `name`   | Workflow name | Yes      |
 
-<!-- politty:command:workflow get:arguments:end -->
-
-<!-- politty:command:workflow get:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description       | Required | Default | Env                            |
@@ -124,47 +69,24 @@ tailor-sdk workflow get [options] <name>
 | `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
 | `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
 
-<!-- politty:command:workflow get:options:end -->
-
-<!-- politty:command:workflow get:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:workflow get:global-options-link:end -->
-<!-- politty:command:workflow start:heading:start -->
-
 ### workflow start
 
-<!-- politty:command:workflow start:heading:end -->
-
-<!-- politty:command:workflow start:description:start -->
-
 Start a workflow execution.
 
-<!-- politty:command:workflow start:description:end -->
-
-<!-- politty:command:workflow start:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk workflow start [options] <name>
 ```
 
-<!-- politty:command:workflow start:usage:end -->
-
-<!-- politty:command:workflow start:arguments:start -->
-
 **Arguments**
 
 | Argument | Description   | Required |
 | -------- | ------------- | -------- |
 | `name`   | Workflow name | Yes      |
 
-<!-- politty:command:workflow start:arguments:end -->
-
-<!-- politty:command:workflow start:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                                                 | Required | Default              | Env                                 |
@@ -175,135 +97,161 @@ tailor-sdk workflow start [options] <name>
 | `--machine-user <MACHINE_USER>` | `-m`  | Machine user name. Falls back to the active profile's default machine user. | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
 | `--arg <ARG>`                   | `-a`  | Workflow argument (JSON string)                                             | No       | -                    | -                                   |
 | `--wait`                        | `-W`  | Wait for execution to complete                                              | No       | `false`              | -                                   |
-| `--interval <INTERVAL>`         | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m')              | No       | `"3s"`               | -                                   |
-| `--logs`                        | `-l`  | Display job execution logs after completion (requires --wait)               | No       | `false`              | -                                   |
-
-<!-- politty:command:workflow start:options:end -->
-
-<!-- politty:command:workflow start:global-options-link:start -->
+| `--interval <INTERVAL>`         | `-i`  | Polling interval when waiting (e.g., '3s', '500ms', '1m')                   | No       | `"3s"`               | -                                   |
+| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait (e.g., '30s', '10m')                                   | No       | `"10m"`              | -                                   |
+| `--until <UNTIL>`               | `-u`  | Wait target (success, suspended, terminal)                                  | No       | `"terminal"`         | -                                   |
+| `--logs`                        | `-l`  | Display job execution logs after completion                                 | No       | `false`              | -                                   |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:workflow start:global-options-link:end -->
-<!-- politty:command:workflow executions:heading:start -->
-
-### workflow executions
+**Usage Examples:**
 
-<!-- politty:command:workflow executions:heading:end -->
+```bash
+# Start a workflow
+tailor-sdk workflow start my-workflow -m admin-machine-user
 
-<!-- politty:command:workflow executions:description:start -->
+# Start with argument
+tailor-sdk workflow start my-workflow -m admin -a '{"userId": "123"}'
 
-List or get workflow executions.
+# Start and wait for completion
+tailor-sdk workflow start my-workflow -m admin -W
+```
 
-<!-- politty:command:workflow executions:description:end -->
+### workflow wait
 
-<!-- politty:command:workflow executions:usage:start -->
+Wait for a workflow execution.
 
 **Usage**
 
 ```
-tailor-sdk workflow executions [options] [execution-id]
+tailor-sdk workflow wait [options] <execution-id>
 ```
 
-<!-- politty:command:workflow executions:usage:end -->
-
-<!-- politty:command:workflow executions:arguments:start -->
-
 **Arguments**
 
-| Argument       | Description                               | Required |
-| -------------- | ----------------------------------------- | -------- |
-| `execution-id` | Execution ID (if provided, shows details) | No       |
-
-<!-- politty:command:workflow executions:arguments:end -->
-
-<!-- politty:command:workflow executions:options:start -->
+| Argument       | Description  | Required |
+| -------------- | ------------ | -------- |
+| `execution-id` | Execution ID | Yes      |
 
 **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`      |
-| `--order <ORDER>`                 | -     | Sort order (asc or desc)                                       | No       | `"desc"` | -                              |
-| `--limit <LIMIT>`                 | `-l`  | Maximum number of items to return (0: unlimited)               | No       | `50`     | -                              |
-| `--workflow-name <WORKFLOW_NAME>` | `-n`  | Filter by workflow name (list mode only)                       | No       | -        | -                              |
-| `--status <STATUS>`               | `-s`  | Filter by status (list mode only)                              | No       | -        | -                              |
-| `--wait`                          | `-W`  | Wait for execution to complete                                 | No       | `false`  | -                              |
-| `--interval <INTERVAL>`           | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No       | `"3s"`   | -                              |
-| `--logs`                          | -     | Display job execution logs (detail mode only)                  | No       | `false`  | -                              |
-
-<!-- politty:command:workflow executions:options:end -->
-
-<!-- politty:command:workflow executions: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`      |
+| `--interval <INTERVAL>`         | `-i`  | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No       | `"3s"`       | -                              |
+| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait (e.g., '30s', '10m')                 | No       | `"10m"`      | -                              |
+| `--until <UNTIL>`               | `-u`  | Wait target (success, suspended, terminal)                | No       | `"terminal"` | -                              |
+| `--logs`                        | `-l`  | Display job execution logs after completion               | No       | `false`      | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:workflow executions:global-options-link:end -->
-<!-- politty:command:workflow resume:heading:start -->
+**Examples**
 
-### workflow resume
+**Wait for workflow success**
 
-<!-- politty:command:workflow resume:heading:end -->
+```bash
+$ tailor-sdk workflow wait execution-id --until success --timeout 10m --json
+```
 
-<!-- politty:command:workflow resume:description:start -->
+**Wait for a workflow wait point**
 
-Resume a failed or pending workflow execution.
+```bash
+$ tailor-sdk workflow wait execution-id --until suspended --timeout 6m --logs --json
+```
 
-<!-- politty:command:workflow resume:description:end -->
+**Wait for success, failure, or suspension**
+
+```bash
+$ tailor-sdk workflow wait execution-id --until terminal
+```
 
-<!-- politty:command:workflow resume:usage:start -->
+**Shell automation**
 
-**Usage**
+Capture the execution ID from `workflow start` and wait for the same run from a
+separate command:
 
+```bash
+execution_id="$(
+  tailor-sdk workflow start order-workflow --json | jq -r '.executionId'
+)"
+
+tailor-sdk workflow wait "$execution_id" \
+  --until success \
+  --timeout 10m \
+  --interval 5s \
+  --json
 ```
-tailor-sdk workflow resume [options] <execution-id>
+
+Wait until a workflow reaches a wait point, such as an approval step:
+
+```bash
+tailor-sdk workflow wait "$execution_id" \
+  --until suspended \
+  --timeout 6m \
+  --logs \
+  --json
 ```
 
-<!-- politty:command:workflow resume:usage:end -->
+**Programmatic API**
 
-<!-- politty:command:workflow resume:arguments:start -->
+Use `waitWorkflowExecution` when a script already has an execution ID and needs
+the same waiter behavior as the CLI:
 
-**Arguments**
+```ts
+import { waitWorkflowExecution } from "@tailor-platform/sdk/cli";
 
-| Argument       | Description         | Required |
-| -------------- | ------------------- | -------- |
-| `execution-id` | Failed execution ID | Yes      |
+const executionId = process.env.EXECUTION_ID;
 
-<!-- politty:command:workflow resume:arguments:end -->
+if (!executionId) {
+  throw new Error("EXECUTION_ID is required");
+}
 
-<!-- politty:command:workflow resume:options:start -->
+const result = await waitWorkflowExecution({
+  executionId,
+  until: "success",
+  timeout: 10 * 60 * 1000,
+  interval: 5000,
+});
 
-**Options**
+if (result.timedOut) {
+  throw new Error(`Workflow ${result.id} timed out at ${result.status}`);
+}
+```
 
-| 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`      |
-| `--wait`                        | `-W`  | Wait for execution to complete                                 | No       | `false` | -                              |
-| `--interval <INTERVAL>`         | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No       | `"3s"`  | -                              |
-| `--logs`                        | `-l`  | Display job execution logs after completion (requires --wait)  | No       | `false` | -                              |
+### workflow executions
 
-<!-- politty:command:workflow resume:options:end -->
+List or get workflow executions.
 
-<!-- politty:command:workflow resume:global-options-link:start -->
+**Usage**
 
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+```
+tailor-sdk workflow executions [options] [execution-id]
+```
 
-<!-- politty:command:workflow resume:global-options-link:end -->
+**Arguments**
 
-**Usage Examples:**
+| Argument       | Description                               | Required |
+| -------------- | ----------------------------------------- | -------- |
+| `execution-id` | Execution ID (if provided, shows details) | No       |
 
-```bash
-# Start a workflow
-tailor-sdk workflow start my-workflow -m admin-machine-user
+**Options**
 
-# Start with argument
-tailor-sdk workflow start my-workflow -m admin -a '{"userId": "123"}'
+| 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`      |
+| `--order <ORDER>`                 | -     | Sort order (asc or desc)                                  | No       | `"desc"`     | -                              |
+| `--limit <LIMIT>`                 | `-l`  | Maximum number of items to return (0: unlimited)          | No       | `50`         | -                              |
+| `--workflow-name <WORKFLOW_NAME>` | `-n`  | Filter by workflow name (list mode only)                  | No       | -            | -                              |
+| `--status <STATUS>`               | `-s`  | Filter by status (list mode only)                         | No       | -            | -                              |
+| `--wait`                          | `-W`  | Wait for execution to complete                            | No       | `false`      | -                              |
+| `--interval <INTERVAL>`           | `-i`  | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No       | `"3s"`       | -                              |
+| `--timeout <TIMEOUT>`             | `-t`  | Maximum time to wait (e.g., '30s', '10m')                 | No       | `"10m"`      | -                              |
+| `--until <UNTIL>`                 | `-u`  | Wait target (success, suspended, terminal)                | No       | `"terminal"` | -                              |
+| `--logs`                          | -     | Display job execution logs (detail mode only)             | No       | `false`      | -                              |
 
-# Start and wait for completion
-tailor-sdk workflow start my-workflow -m admin -W
-```
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Usage Examples:**
 
@@ -326,3 +274,33 @@ tailor-sdk workflow executions <execution-id> --logs
 # Wait for execution to complete
 tailor-sdk workflow executions <execution-id> -W
 ```
+
+### workflow resume
+
+Resume a failed or pending workflow execution.
+
+**Usage**
+
+```
+tailor-sdk workflow resume [options] <execution-id>
+```
+
+**Arguments**
+
+| Argument       | Description         | Required |
+| -------------- | ------------------- | -------- |
+| `execution-id` | Failed execution ID | Yes      |
+
+**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`      |
+| `--wait`                        | `-W`  | Wait for execution to complete                            | No       | `false`      | -                              |
+| `--interval <INTERVAL>`         | `-i`  | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No       | `"3s"`       | -                              |
+| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait (e.g., '30s', '10m')                 | No       | `"10m"`      | -                              |
+| `--until <UNTIL>`               | `-u`  | Wait target (success, suspended, terminal)                | No       | `"terminal"` | -                              |
+| `--logs`                        | `-l`  | Display job execution logs after completion               | No       | `false`      | -                              |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.