Skip to content

Commit 2991ef2

Browse files
tailor-docs-bot[bot]tailor-docs-bot[bot]
committed
Update SDK pages
1 parent afa0043 commit 2991ef2

3 files changed

Lines changed: 211 additions & 20 deletions

File tree

‎docs/sdk/cli-reference.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@ Commands for managing workflows and executions.
223223
| [workflow list](cli/workflow.md#workflow-list) | List all workflows in the workspace. |
224224
| [workflow get](cli/workflow.md#workflow-get) | Get workflow details. |
225225
| [workflow start](cli/workflow.md#workflow-start) | Start a workflow execution. |
226+
| [workflow wait](cli/workflow.md#workflow-wait) | Wait for a workflow execution. |
226227
| [workflow executions](cli/workflow.md#workflow-executions) | List or get workflow executions. |
227228
| [workflow resume](cli/workflow.md#workflow-resume) | Resume a failed or pending workflow execution. |
228229

‎docs/sdk/cli/executor.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,7 @@ tailor-sdk executor jobs [options] <executor-name> [job-id]
179179
| `--attempts` | - | Show job attempts (only with job ID) (detail mode only) | No | `false` | - |
180180
| `--wait` | `-W` | Wait for job completion and downstream execution (workflow/function) if applicable (detail mode only) | No | `false` | - |
181181
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
182+
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait when using --wait (e.g., '30s', '5m') | No | `"5m"` | - |
182183
| `--order <ORDER>` | - | Sort order (asc or desc) | No | `"desc"` | - |
183184
| `--limit <LIMIT>` | - | Maximum number of jobs to list (0: unlimited, default: 50) (list mode only) | No | `50` | - |
184185
| `--logs` | `-l` | Display function execution logs after completion (requires --wait) | No | `false` | - |
@@ -283,6 +284,7 @@ tailor-sdk executor trigger [options] <executor-name>
283284
| `--header <HEADER>` | `-H` | Request header (format: 'Key: Value', can be specified multiple times) | No | - | - |
284285
| `--wait` | `-W` | Wait for job completion and downstream execution (workflow/function) if applicable | No | `false` | - |
285286
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
287+
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait when using --wait (e.g., '30s', '5m') | No | `"5m"` | - |
286288
| `--logs` | `-l` | Display function execution logs after completion (requires --wait) | No | `false` | - |
287289

288290
<!-- politty:command:executor trigger:options:end -->
@@ -323,6 +325,57 @@ $ tailor-sdk executor trigger my-executor -W -l
323325

324326
<!-- politty:command:executor trigger:examples:end -->
325327

328+
**Shell automation**
329+
330+
Trigger an executor and wait for the executor job plus any downstream workflow or
331+
function execution:
332+
333+
```bash
334+
tailor-sdk executor trigger daily-workflow \
335+
--wait \
336+
--timeout 5m \
337+
--interval 5s \
338+
--json
339+
```
340+
341+
Wait for an existing job when another process already captured the job ID:
342+
343+
```bash
344+
tailor-sdk executor jobs daily-workflow "$job_id" \
345+
--wait \
346+
--timeout 5m \
347+
--logs \
348+
--json
349+
```
350+
351+
**Programmatic API**
352+
353+
Import your executor definition and pass it to the typed API:
354+
355+
```ts
356+
import { triggerExecutor, watchExecutorJob } from "@tailor-platform/sdk/cli";
357+
import dailyWorkflow from "../executors/dailyWorkflow";
358+
359+
const { jobId } = await triggerExecutor({
360+
executor: dailyWorkflow,
361+
});
362+
363+
if (!jobId) {
364+
throw new Error("Executor trigger did not return a job ID");
365+
}
366+
367+
const result = await watchExecutorJob({
368+
executor: dailyWorkflow,
369+
jobId,
370+
timeout: 5 * 60 * 1000,
371+
interval: 5000,
372+
});
373+
374+
if (result.timedOut) {
375+
throw new Error(`Executor job ${result.job.id} timed out at ${result.job.status}`);
376+
}
377+
```
378+
326379
<!-- politty:command:executor trigger:notes:start -->
327380

328381
**Notes**

‎docs/sdk/cli/workflow.md‎

Lines changed: 157 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ tailor-sdk workflow [command]
3333
| [`workflow list`](#workflow-list) | List all workflows in the workspace. |
3434
| [`workflow get`](#workflow-get) | Get workflow details. |
3535
| [`workflow start`](#workflow-start) | Start a workflow execution. |
36+
| [`workflow wait`](#workflow-wait) | Wait for a workflow execution. |
3637
| [`workflow executions`](#workflow-executions) | List or get workflow executions. |
3738
| [`workflow resume`](#workflow-resume) | Resume a failed or pending workflow execution. |
3839

@@ -175,8 +176,10 @@ tailor-sdk workflow start [options] <name>
175176
| `--machine-user <MACHINE_USER>` | `-m` | Machine user name. Falls back to the active profile's default machine user. | No | - | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
176177
| `--arg <ARG>` | `-a` | Workflow argument (JSON string) | No | - | - |
177178
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
178-
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
179-
| `--logs` | `-l` | Display job execution logs after completion (requires --wait) | No | `false` | - |
179+
| `--interval <INTERVAL>` | `-i` | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
180+
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait (e.g., '30s', '10m') | No | `"10m"` | - |
181+
| `--until <UNTIL>` | `-u` | Wait target (success, suspended, terminal) | No | `"terminal"` | - |
182+
| `--logs` | `-l` | Display job execution logs after completion | No | `false` | - |
180183

181184
<!-- politty:command:workflow start:options:end -->
182185

@@ -185,6 +188,136 @@ tailor-sdk workflow start [options] <name>
185188
See [Global Options](../cli-reference.md#global-options) for options available to all commands.
186189

187190
<!-- politty:command:workflow start:global-options-link:end -->
191+
<!-- politty:command:workflow wait:heading:start -->
192+
193+
### workflow wait
194+
195+
<!-- politty:command:workflow wait:heading:end -->
196+
197+
<!-- politty:command:workflow wait:description:start -->
198+
199+
Wait for a workflow execution.
200+
201+
<!-- politty:command:workflow wait:description:end -->
202+
203+
<!-- politty:command:workflow wait:usage:start -->
204+
205+
**Usage**
206+
207+
```
208+
tailor-sdk workflow wait [options] <execution-id>
209+
```
210+
211+
<!-- politty:command:workflow wait:usage:end -->
212+
213+
<!-- politty:command:workflow wait:arguments:start -->
214+
215+
**Arguments**
216+
217+
| Argument | Description | Required |
218+
| -------------- | ------------ | -------- |
219+
| `execution-id` | Execution ID | Yes |
220+
221+
<!-- politty:command:workflow wait:arguments:end -->
222+
223+
<!-- politty:command:workflow wait:options:start -->
224+
225+
**Options**
226+
227+
| Option | Alias | Description | Required | Default | Env |
228+
| ------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
229+
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
230+
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
231+
| `--interval <INTERVAL>` | `-i` | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
232+
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait (e.g., '30s', '10m') | No | `"10m"` | - |
233+
| `--until <UNTIL>` | `-u` | Wait target (success, suspended, terminal) | No | `"terminal"` | - |
234+
| `--logs` | `-l` | Display job execution logs after completion | No | `false` | - |
235+
236+
<!-- politty:command:workflow wait:options:end -->
237+
238+
<!-- politty:command:workflow wait:global-options-link:start -->
239+
240+
See [Global Options](../cli-reference.md#global-options) for options available to all commands.
241+
242+
<!-- politty:command:workflow wait:global-options-link:end -->
243+
244+
<!-- politty:command:workflow wait:examples:start -->
245+
246+
**Examples**
247+
248+
**Wait for workflow success**
249+
250+
```bash
251+
$ tailor-sdk workflow wait execution-id --until success --timeout 10m --json
252+
```
253+
254+
**Wait for a workflow wait point**
255+
256+
```bash
257+
$ tailor-sdk workflow wait execution-id --until suspended --timeout 6m --logs --json
258+
```
259+
260+
**Wait for success, failure, or suspension**
261+
262+
```bash
263+
$ tailor-sdk workflow wait execution-id --until terminal
264+
```
265+
266+
<!-- politty:command:workflow wait:examples:end -->
267+
268+
**Shell automation**
269+
270+
Capture the execution ID from `workflow start` and wait for the same run from a
271+
separate command:
272+
273+
```bash
274+
execution_id="$(
275+
tailor-sdk workflow start order-workflow --json | jq -r '.executionId'
276+
)"
277+
278+
tailor-sdk workflow wait "$execution_id" \
279+
--until success \
280+
--timeout 10m \
281+
--interval 5s \
282+
--json
283+
```
284+
285+
Wait until a workflow reaches a wait point, such as an approval step:
286+
287+
```bash
288+
tailor-sdk workflow wait "$execution_id" \
289+
--until suspended \
290+
--timeout 6m \
291+
--logs \
292+
--json
293+
```
294+
295+
**Programmatic API**
296+
297+
Use `waitWorkflowExecution` when a script already has an execution ID and needs
298+
the same waiter behavior as the CLI:
299+
300+
```ts
301+
import { waitWorkflowExecution } from "@tailor-platform/sdk/cli";
302+
303+
const executionId = process.env.EXECUTION_ID;
304+
305+
if (!executionId) {
306+
throw new Error("EXECUTION_ID is required");
307+
}
308+
309+
const result = await waitWorkflowExecution({
310+
executionId,
311+
until: "success",
312+
timeout: 10 * 60 * 1000,
313+
interval: 5000,
314+
});
315+
316+
if (result.timedOut) {
317+
throw new Error(`Workflow ${result.id} timed out at ${result.status}`);
318+
}
319+
```
320+
188321
<!-- politty:command:workflow executions:heading:start -->
189322

190323
### workflow executions
@@ -221,17 +354,19 @@ tailor-sdk workflow executions [options] [execution-id]
221354

222355
**Options**
223356

224-
| Option | Alias | Description | Required | Default | Env |
225-
| --------------------------------- | ----- | -------------------------------------------------------------- | -------- | -------- | ------------------------------ |
226-
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
227-
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
228-
| `--order <ORDER>` | - | Sort order (asc or desc) | No | `"desc"` | - |
229-
| `--limit <LIMIT>` | `-l` | Maximum number of items to return (0: unlimited) | No | `50` | - |
230-
| `--workflow-name <WORKFLOW_NAME>` | `-n` | Filter by workflow name (list mode only) | No | - | - |
231-
| `--status <STATUS>` | `-s` | Filter by status (list mode only) | No | - | - |
232-
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
233-
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
234-
| `--logs` | - | Display job execution logs (detail mode only) | No | `false` | - |
357+
| Option | Alias | Description | Required | Default | Env |
358+
| --------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
359+
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
360+
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
361+
| `--order <ORDER>` | - | Sort order (asc or desc) | No | `"desc"` | - |
362+
| `--limit <LIMIT>` | `-l` | Maximum number of items to return (0: unlimited) | No | `50` | - |
363+
| `--workflow-name <WORKFLOW_NAME>` | `-n` | Filter by workflow name (list mode only) | No | - | - |
364+
| `--status <STATUS>` | `-s` | Filter by status (list mode only) | No | - | - |
365+
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
366+
| `--interval <INTERVAL>` | `-i` | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
367+
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait (e.g., '30s', '10m') | No | `"10m"` | - |
368+
| `--until <UNTIL>` | `-u` | Wait target (success, suspended, terminal) | No | `"terminal"` | - |
369+
| `--logs` | - | Display job execution logs (detail mode only) | No | `false` | - |
235370

236371
<!-- politty:command:workflow executions:options:end -->
237372

@@ -276,13 +411,15 @@ tailor-sdk workflow resume [options] <execution-id>
276411

277412
**Options**
278413

279-
| Option | Alias | Description | Required | Default | Env |
280-
| ------------------------------- | ----- | -------------------------------------------------------------- | -------- | ------- | ------------------------------ |
281-
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
282-
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
283-
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
284-
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
285-
| `--logs` | `-l` | Display job execution logs after completion (requires --wait) | No | `false` | - |
414+
| Option | Alias | Description | Required | Default | Env |
415+
| ------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
416+
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
417+
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
418+
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
419+
| `--interval <INTERVAL>` | `-i` | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
420+
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait (e.g., '30s', '10m') | No | `"10m"` | - |
421+
| `--until <UNTIL>` | `-u` | Wait target (success, suspended, terminal) | No | `"terminal"` | - |
422+
| `--logs` | `-l` | Display job execution logs after completion | No | `false` | - |
286423

287424
<!-- politty:command:workflow resume:options:end -->
288425

0 commit comments

Comments
 (0)