# Workflows (/cli/workflows)

Build, deploy, run, and inspect workflows from the terminal.

`sim workflows` is also spelled `sim workflow`.

These commands accept the [global options](/cli/commands#global-options).

## Workflows \[#workflows]

### List workflows \[#list-workflows]

```bash
sim workflows list [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. The folder filter resolves against active folders only, so pairing it with `archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
| `--deployed-only` | No | Return only workflows with an active deployment when true. |
| `--no-deployed-only` | No | Send --deployed-only as false. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
| `--search <value>` | No | Case-insensitive substring match against the resource name. |
| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "position". Accepted values: `position`, `name`, `createdAt`, `updatedAt`, `runCount`. |
| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |

API request and response schemas: [listWorkflows](/api-reference/workflows/listWorkflows).

### Get workflow \[#get-workflow]

```bash
sim workflows get <workflowId>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

API request and response schemas: [getWorkflow](/api-reference/workflows/getWorkflow).

### Create workflow \[#create-workflow]

```bash
sim workflows create [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | Yes | Workflow name. |
| `--description <value>` | No | Optional workflow description. |
| `--folder <value>` | No | Existing folder path (leading / optional); create it first with sim workflows mkdir \<path>. |

API request and response schemas: [createWorkflow](/api-reference/workflows/createWorkflowV2).

### Update workflow \[#update-workflow]

```bash
sim workflows update <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | No | Replacement workflow name. |
| `--description <value>` | No | Replacement workflow description; null clears it. (--description null sends the word, not JSON null). |
| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |

API request and response schemas: [updateWorkflow](/api-reference/workflows/updateWorkflowV2).

### Duplicate workflow \[#duplicate-workflow]

```bash
sim workflows duplicate create <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | No | Name for the copy. Defaults to the source name, deduplicated within the folder. |
| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |

API request and response schemas: [duplicateWorkflow](/api-reference/workflows/duplicateWorkflow).

### Move workflows \[#move-workflows]

```bash
sim workflows move [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--workflow <value...>` | Yes | Workflows to move. Duplicates are collapsed. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
| `--to <value>` | Yes | Destination folder path; / moves the workflows to the workspace root. |

API request and response schemas: [moveWorkflows](/api-reference/workflows/moveWorkflows).

### Move a workflow to a folder \[#move-a-workflow-to-a-folder]

```bash
sim workflows mv <workflowId> <folder>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |
| `folder` | Yes | Folder path as shown in the app; the leading / is optional |

API request and response schemas: [updateWorkflow](/api-reference/workflows/updateWorkflowV2).

### Delete workflow \[#delete-workflow]

This archives the workflow and its run history; restore with `workflows restore`.

```bash
sim workflows delete <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [deleteWorkflow](/api-reference/workflows/deleteWorkflowV2).

### Restore an archived workflow \[#restore-an-archived-workflow]

```bash
sim workflows restore <workflowId>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

API request and response schemas: [restoreWorkflow](/api-reference/workflows/restoreWorkflow).

## Draft state and edits \[#draft-state-and-edits]

### Get workflow state \[#get-workflow-state]

```bash
sim workflows state get <workflowId>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

API request and response schemas: [getWorkflowState](/api-reference/workflows/getWorkflowState).

### Replace workflow state \[#replace-workflow-state]

OAuth login or personal API key required.

This replaces the entire draft graph and cannot be undone.

```bash
sim workflows state replace <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--dry-run` | No | Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs. |
| `--no-dry-run` | No | Send --dry-run as false. |
| `--blocks <json\|@file>` | Yes | Blocks keyed by block id. (JSON, or @path / @- to read a file or stdin). |
| `--edges <json\|@file>` | Yes | Directed connections between blocks. (JSON, or @path / @- to read a file or stdin). |
| `--loops <json\|@file>` | No | Ignored on write: loop containers are recomputed from `blocks`. (JSON, or @path / @- to read a file or stdin). |
| `--parallels <json\|@file>` | No | Ignored on write: parallel containers are recomputed from `blocks`. (JSON, or @path / @- to read a file or stdin). |
| `--variables <json\|@file>` | No | Replacement variable set. Omit to leave the stored variables untouched. (JSON, or @path / @- to read a file or stdin). |
| `-y, --yes` | Conditional | Confirm this operation (required unless --dry-run). |

API request and response schemas: [replaceWorkflowState](/api-reference/workflows/replaceWorkflowState).

### Edit a workflow’s blocks, connections and settings with a batch of operations \[#edit-a-workflows-blocks-connections-and-settings-with-a-batch-of-operations]

OAuth login or personal API key required.

This edits the draft graph: the batch adds, edits, or deletes blocks and their edges as written.

```bash
sim workflows operations apply <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--dry-run` | No | Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs. |
| `--no-dry-run` | No | Send --dry-run as false. |
| `--operations <json\|@file>` | Yes | Edits to apply, in a single batch, keyed by operation\_type: \[{"operation\_type":"add","block\_id":"my-fn","params":{"type":"function","name":"My Fn","inputs":{"code":"return {ok:true}"}}},{"operation\_type":"edit","block\_id":"\<uuid>","params":{"name":"Renamed","connections":{"success":"my-fn"}}},{"operation\_type":"delete","block\_id":"\<uuid>"}]. Also extract\_from\_subflow, whose params carry {"subflowId":"\<loop-id>"}, and insert\_into\_subflow, which creates a block and so takes an add’s params plus that subflowId (JSON, or @path / @- to read a file or stdin). |
| `--atomic` | No | Fail the whole batch when any operation is declined or any block input would be dropped. The default applies what it can and reports the rest in `skipped` and `inputValidationErrors`; `true` writes nothing and answers `409` instead. |
| `--no-atomic` | No | Send --atomic as false. |
| `--layout <value>` | No | Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied. Accepted values: `targeted`, `none`. |
| `--set-block-enabled <json\|@file>` | No | Blocks to enable or disable, applied after --operations: \[{"block\_id":"\<uuid>","enabled":false}]. Disabling a loop or parallel cascades to its unlocked descendants; enabling a block whose container is disabled is declined (JSON, or @path / @- to read a file or stdin). |
| `-y, --yes` | Conditional | Confirm this operation (required unless --dry-run). |

API request and response schemas: [applyWorkflowOperations](/api-reference/workflows/applyWorkflowOperations).

### Update workflow variables \[#update-workflow-variables]

This applies the listed variable changes; variables omitted from the operations remain unchanged.

```bash
sim workflows variables update <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--operations <json\|@file>` | Yes | Variable changes to apply in order, keyed by operation: \[{"operation":"add","name":"my\_var","type":"string","value":"hello"},{"operation":"edit","name":"my\_var","value":"updated"},{"operation":"delete","name":"my\_var"}] (JSON, or @path / @- to read a file or stdin). |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [applyWorkflowVariables](/api-reference/workflows/applyWorkflowVariables).

## Deployments and versions \[#deployments-and-versions]

### Deploy workflow \[#deploy-workflow]

OAuth login or personal API key required.

```bash
sim workflows deploy <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | No | Optional label for the deployment version. |
| `--description <value>` | No | Optional release note for the deployment version. |

API request and response schemas: [deployWorkflow](/api-reference/workflows/deployWorkflow).

### Show a workflow’s current deployment \[#show-a-workflows-current-deployment]

```bash
sim workflows deployment status <workflowId>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

API request and response schemas: [getWorkflowDeployment](/api-reference/workflows/getWorkflowDeployment).

### Update workflow public API access \[#update-workflow-public-api-access]

OAuth login or personal API key required.

```bash
sim workflows deployment update <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--is-public-api <true\|false>` | Yes | Whether the deployed workflow should accept unauthenticated public API execution. Accepted values: `true`, `false`. |

API request and response schemas: [updateWorkflowPublicApi](/api-reference/workflows/updateWorkflowPublicApi).

### List workflow versions \[#list-workflow-versions]

```bash
sim workflows versions list <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |

API request and response schemas: [listWorkflowVersions](/api-reference/workflows/listWorkflowVersionsV2).

### Get workflow version \[#get-workflow-version]

```bash
sim workflows versions get <workflowId> <version>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |
| `version` | Yes | Numeric deployment version. |

API request and response schemas: [getWorkflowVersion](/api-reference/workflows/getWorkflowVersionV2).

### Update workflow version \[#update-workflow-version]

```bash
sim workflows versions update <workflowId> <version> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |
| `version` | Yes | Numeric deployment version. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--name <value>` | No | New label for the deployment version. |
| `--description <value>` | No | New release note for the deployment version, or null to clear it. (--description null sends the word, not JSON null). |

API request and response schemas: [updateWorkflowVersion](/api-reference/workflows/updateWorkflowVersionV2).

### Compare workflow versions \[#compare-workflow-versions]

```bash
sim workflows versions compare <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--base <value>` | Yes | Deployment version to compare from. |
| `--target <value>` | Yes | Deployment version to compare to, in the same workflow. |

API request and response schemas: [compareWorkflowVersions](/api-reference/workflows/compareWorkflowVersionsV2).

### Activate workflow version \[#activate-workflow-version]

OAuth login or personal API key required.

This changes which deployed version runs in production for every API and chat consumer.

```bash
sim workflows activate create <workflowId> <version> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |
| `version` | Yes | Numeric deployment version. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [activateWorkflowVersion](/api-reference/workflows/activateWorkflowVersion).

### Revert workflow to version \[#revert-workflow-to-version]

OAuth login or personal API key required.

This overwrites the draft graph with the selected version and cannot be undone.

```bash
sim workflows revert create <workflowId> <version> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |
| `version` | Yes | Numeric deployment version, or `active` for the currently live version. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [revertWorkflowVersion](/api-reference/workflows/revertWorkflowVersion).

### Rollback workflow \[#rollback-workflow]

OAuth login or personal API key required.

This changes which deployed version runs in production for every API and chat consumer.

```bash
sim workflows rollback <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--to-version <value>` | No | Deployment version to reactivate. Omit to select the previous active version. |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [rollbackWorkflow](/api-reference/workflows/rollbackWorkflow).

### Take a workflow out of deployment \[#take-a-workflow-out-of-deployment]

OAuth login or personal API key required.

This takes the workflow offline for every API and chat consumer, and agents calling its MCP tools lose access until it is deployed again.

```bash
sim workflows undeploy <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [undeployWorkflow](/api-reference/workflows/undeployWorkflow).

## Run and inspect \[#run-and-inspect]

### Run a deployed workflow or execute saved state manually \[#run-a-deployed-workflow-or-execute-saved-state-manually]

```bash
sim workflows run <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--input <json\|@file>` | No | Trigger input as JSON (JSON, or @path / @- to read a file or stdin). |
| `--async` | No | Queue the run and return immediately. Defaults to false. |
| `--execution-timeout-seconds <value>` | No | Maximum duration of the run in seconds, capped by the plan's execution timeout. Requires --async or --wait-timeout. |
| `--select-output <value...>` | No | Return blockName.path values (e.g. agent\_1.content), or childWorkflowId.blockName.path for a child workflow (applies to every invocation) — in blockOutputs on a sync run, or from the streamed result with --follow; missing paths are omitted. Not available with --async (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
| `--include-file-base64` | No | Inline eligible output files as base64 content. Defaults to true for the installed CLI; Chat defaults to file references and admits requested bytes only for synchronous runs. Rejected when async is true. |
| `--no-include-file-base64` | No | Send --include-file-base64 as false. |
| `--base64-max-bytes <value>` | No | Maximum total bytes of file content to inline as base64, lowering but never raising the server limit of 16 MiB. Rejected when `async` is true. |
| `--run-id <value>` | No | One-shot identifier for this run; NOT an idempotency key — reusing a claimed value fails with RUN\_ID\_CONFLICT instead of replaying the first result, and a fresh value starts another run. |
| `--manual` | No | Run the current saved workflow state instead of the active deployment. |
| `--trigger <blockId>` | No | Enter the run through this runnable trigger; runs the current saved workflow state (implies --manual). |
| `--mock-payload` | No | Use the selected trigger's server-derived mock payload; runs the current saved workflow state (implies --manual). |
| `--from-block <blockId>` | No | Run manually from this saved workflow block. |
| `--source-run <runId>` | No | Prior run whose persisted state supplies upstream outputs (requires --from-block). |
| `--stop-after <blockId>` | No | Stop the run after this saved block, failing it if the run takes a path that skips the block; with --from-block on the same block, re-runs only that block (implies --manual). |
| `--wait-timeout <seconds>` | No | Wait at most this many seconds for a synchronous run (0 waits until it settles). A run still going then continues in the background under async limits: the command prints its run record and exits 4, and `sim workflows runs wait` keeps waiting. Not with --async or --follow. |
| `--follow` | No | Stream the run as it happens; progress on stderr, result on stdout. The stream reports only success and output, so the result omits the run id and timings a non-streaming run returns. |
| `--include-thinking` | No | Show model reasoning while following (requires --follow). |
| `--include-tool-calls` | No | Show tool calls while following (requires --follow). |

API request and response schemas: [executeWorkflow](/api-reference/workflows/executeWorkflowV2).

### List runs for a workflow \[#list-runs-for-a-workflow]

```bash
sim workflows runs list [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--workflow <workflowId>` | Yes | Workflow ID. |
| `--status <value>` | No | Filter by run status. Accepted values: `pending`, `running`, `completed`, `failed`, `cancelled`, `paused`. |
| `--trigger <value>` | No | Filter by trigger type. |
| `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
| `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
| `--order <value>` | No | Sort direction by run start time. This list is sortable only by run start time, so it takes `order` in place of `sortBy`/`sortOrder`, which it rejects. Defaults to "desc". Accepted values: `asc`, `desc`. |

API request and response schemas: [listWorkflowRuns](/api-reference/workflow-runs/listWorkflowRunsV2).

### Show run status \[#show-run-status]

Requested outputs are included in JSON or YAML output.

```bash
sim workflows runs get <runId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `runId` | Yes | Unique workflow run identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--workflow <workflowId>` | Yes | Workflow ID. |
| `--include-output` | No | Include the final output in JSON or YAML output. |
| `--select-output <value...>` | No | Include blockName.path or blockId.path values (e.g. agent\_1.content) in JSON or YAML output; names resolve against the workflow’s current blocks, and missing paths are omitted (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
| `--include-file-base64` | No | Inline each produced file's bytes as base64. Requires `includeOutput`. A file above the inline ceiling answers `413` naming its download path; fetch large files from `downloadPath` instead. |
| `--no-include-file-base64` | No | Send --include-file-base64 as false. |
| `--base64-max-bytes <value>` | No | Per-file inline ceiling, lowering but never raising the server limit of 16 MiB. |

API request and response schemas: [getWorkflowRun](/api-reference/workflow-runs/getWorkflowRunV2).

### Wait until a run finishes or needs input \[#wait-for-a-run-to-reach-a-terminal-state-then-show-it]

```bash
sim workflows runs wait <runId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `runId` | Yes | Unique workflow run identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--workflow <workflowId>` | Yes | Workflow ID. |
| `--wait-timeout <seconds>` | No | Give up after this many seconds, or 0 to wait indefinitely (default: 3600). Bounds the whole wait; SIM\_TIMEOUT\_SECONDS bounds one request. |

Exit codes: 0 completed, 1 failed, 2 cancelled, 3 needs input, 4 timed out. Time-based pauses continue waiting; a human pause or an unspecified pause kind ends the wait with code 3. Use `sim workflows runs resume` with the pause context to continue.

API request and response schemas: [getWorkflowRun](/api-reference/workflow-runs/getWorkflowRunV2).

### Resume a paused run \[#resume-a-paused-run]

Output is included in JSON or YAML output.

```bash
sim workflows runs resume <runId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `runId` | Yes | Unique workflow run identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--workflow <workflowId>` | Yes | Workflow ID. |
| `--context <value>` | Yes | Pause context ID returned by run status. |
| `--input <json\|@file>` | No | Resume input as JSON (JSON, or @path / @- to read a file or stdin). |

API request and response schemas: [resumeWorkflow](/api-reference/workflow-runs/resumeWorkflowRunV2).

### Cancel a running workflow run \[#cancel-a-running-workflow-run]

Canceling a paused run prevents resuming that run. Starting a new run can repeat side effects already performed.

```bash
sim workflows runs cancel <runId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `runId` | Yes | Unique workflow run identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--workflow <workflowId>` | Yes | Workflow ID. |

API request and response schemas: [cancelWorkflowRun](/api-reference/workflow-runs/cancelRunV2).

## Chat deployments \[#chat-deployments]

### Show a workflow’s chat deployment \[#show-a-workflows-chat-deployment]

OAuth login or personal API key required.

```bash
sim workflows chat status <workflowId>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

API request and response schemas: [getWorkflowChatDeployment](/api-reference/workflows/getWorkflowChatDeployment).

### Deploy or replace a workflow chat \[#publish-or-replace-a-workflows-chat-deployment]

OAuth login or personal API key required.

This replaces visitor access settings for the chat deployment. Omitted authentication fields reset to defaults, including the password and allowed-email list; avatar and welcome-message behavior follows their option descriptions.

Omitting `--auth-type` selects public access: anyone holding the URL can chat. Supply the complete password or allow-list settings again when replacing a restricted deployment.

```bash
sim workflows chat publish <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--identifier <value>` | Yes | URL slug the deployed chat answers on. Must be free across live deployments. |
| `--title <value>` | Yes | Title shown to visitors. |
| `--description <value>` | No | Description shown to visitors. Omitted clears it. |
| `--customizations <json\|@file>` | No | Presentation overrides. Omitted `primaryColor` and `welcomeMessage` use platform defaults; an omitted or empty `imageUrl` keeps the existing avatar. An empty `welcomeMessage` keeps the existing message. (JSON, or @path / @- to read a file or stdin). |
| `--auth-type <value>` | No | How visitors are gated. `public` leaves the chat open to anyone holding the URL. Defaults to "public". Accepted values: `public`, `password`, `email`, `sso`. |
| `--password <value>` | Conditional | Write-only password of 15 to 1024 characters, not only whitespace. Required whenever `authType` is `password`, and rejected otherwise. Never readable back. Taken literally, except that a request from the Sim agent resolves a whole-value `{{ENV_VAR}}` reference to that variable before the rules apply. |
| `--allowed-emails <json\|@file>` | No | Email addresses or domains admitted under `email` and `sso` gating. At least one is required for those modes. (JSON, or @path / @- to read a file or stdin). |
| `--output-configs <json\|@file>` | No | Block outputs to surface to visitors. Omitted surfaces none. (JSON, or @path / @- to read a file or stdin). |
| `--include-thinking` | No | Allow visitors to receive provider thinking events. Defaults to false. |
| `--no-include-thinking` | No | Send --include-thinking as false. |
| `--include-tool-calls` | No | Allow visitors to receive tool lifecycle events. Defaults to false. |
| `--no-include-tool-calls` | No | Send --include-tool-calls as false. |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [replaceWorkflowChatDeployment](/api-reference/workflows/replaceWorkflowChatDeployment).

### Take a workflow’s chat deployment offline \[#take-a-workflows-chat-deployment-offline]

OAuth login or personal API key required.

This takes the chat offline and frees its identifier. The workflow itself stays deployed and executable.

```bash
sim workflows chat unpublish <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [deleteWorkflowChatDeployment](/api-reference/workflows/deleteWorkflowChatDeployment).

## Export and import \[#export-and-import]

### Print a workflow as a portable JSON document \[#print-a-workflow-as-a-portable-json-document]

The export clears credentials, passwords, and table sub-block values, but it is not a general secret scanner. Inspect literal variables and inline configuration before sharing the document.

```bash
sim workflows export <workflowId> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `workflowId` | Yes | Unique workflow identifier. |

**Options**

| Option | Required | Description |
| - | - | - |
| `--include-references` | No | Include non-secret resource identities for mapped import. |
| `--include-workspace-bindings` | No | Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered credential fields and opaque table/tool values are cleared either way; environment references and ordinary workflow variables remain included. |
| `--no-include-workspace-bindings` | No | Send --include-workspace-bindings as false. |

API request and response schemas: [exportWorkflow](/api-reference/workflows/exportWorkflow).

### Preview workflow import \[#preview-workflow-import]

```bash
sim workflows import-preview [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--workflow <json\|@file>` | Yes | Workflow export object, bare workflow state, or JSON string containing either form. (JSON, or @path / @- to read a file or stdin). |
| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
| `--name <value>` | No | Override for the imported workflow name. |
| `--description <value>` | No | Override for the imported workflow description. |
| `--mappings <json\|@file>` | No | Mapping entries addressed by resource kind and source identifier. (JSON, or @path / @- to read a file or stdin). |
| `--bindings <json\|@file>` | No | Resolved and unresolved source occurrences with their destination selections. (JSON, or @path / @- to read a file or stdin). |
| `--dependent-values <json\|@file>` | No | Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated. (JSON, or @path / @- to read a file or stdin). |

API request and response schemas: [previewWorkflowImport](/api-reference/workspace-sync/previewWorkflowImport).

### Import workflow \[#import-workflow]

```bash
sim workflows import [options]
```

**Options**

| Option | Required | Description |
| - | - | - |
| `--workflow <json\|@file>` | Yes | Workflow export object, bare workflow state, or JSON string containing either form. (JSON, or @path / @- to read a file or stdin). |
| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
| `--name <value>` | No | Override for the imported workflow name. |
| `--description <value>` | No | Override for the imported workflow description. |
| `--mappings <json\|@file>` | No | Mapping entries addressed by resource kind and source identifier. (JSON, or @path / @- to read a file or stdin). |
| `--bindings <json\|@file>` | No | Resolved and unresolved source occurrences with their destination selections. (JSON, or @path / @- to read a file or stdin). |
| `--dependent-values <json\|@file>` | No | Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated. (JSON, or @path / @- to read a file or stdin). |
| `--request-id <value>` | No | Stable client request ID for mapped import. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can create another workflow. |
| `--preview-fingerprint <value>` | No | Fingerprint returned by an import preview with the same choices. A changed plan returns 409; preview again. Do not invent this value. |
| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |

API request and response schemas: [importWorkflow](/api-reference/workflows/importWorkflow).

## Folders \[#folders]

### List workflow resources and child folders together \[#list-workflow-resources-and-child-folders-together]

```bash
sim workflows ls [path] [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | No | Folder path to list; defaults to the root folder |

**Options**

| Option | Required | Description |
| - | - | - |
| `--search <text>` | No | Filter folders and resources by name. |
| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |

API request and response schemas: [listWorkflows](/api-reference/workflows/listWorkflows), [listWorkflowFolders](/api-reference/workflows/listWorkflowsFolders).

### List workflow folders \[#list-workflow-folders]

```bash
sim workflows folders list [options]
```

Also available as `sim workflows folders ls`.

**Options**

| Option | Required | Description |
| - | - | - |
| `--parent <value>` | No | Direct parent folder path. |
| `--search <value>` | No | Case-insensitive substring match against the folder name. |
| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |

API request and response schemas: [listWorkflowFolders](/api-reference/workflows/listWorkflowsFolders).

### Create a workflow folder at a path \[#create-a-workflow-folder-at-a-path]

```bash
sim workflows folders create <path>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path as shown in the app; the leading / is optional |

API request and response schemas: [createWorkflowFolder](/api-reference/workflows/createWorkflowsFolder).

### Delete workflow folder \[#delete-workflow-folder]

This archives the workflow folder and, when recursive, everything inside it.

```bash
sim workflows folders delete <path> [options]
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path as shown in the app; the leading / is optional |

**Options**

| Option | Required | Description |
| - | - | - |
| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
| `-y, --yes` | Yes | Confirm this operation. |

API request and response schemas: [deleteWorkflowFolder](/api-reference/workflows/deleteWorkflowsFolder).

### Rename or move a workflow folder \[#rename-or-move-a-workflow-folder]

```bash
sim workflows folders move <path> <destination>
```

Also available as `sim workflows folders mv`.

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path as shown in the app; the leading / is optional |
| `destination` | Yes | Folder path as shown in the app; the leading / is optional |

API request and response schemas: [relocateWorkflowFolder](/api-reference/workflows/relocateWorkflowsFolder).

### Create a workflow directory at a path \[#create-a-workflow-directory-at-a-path]

```bash
sim workflows mkdir <path>
```

**Arguments**

| Argument | Required | Description |
| - | - | - |
| `path` | Yes | Folder path to create; the leading / is optional |

API request and response schemas: [createWorkflowFolder](/api-reference/workflows/createWorkflowsFolder).

## Related docs \[#related-docs]

- [Workflow builder](/workflows)
- [Import and workspace sync](/cli/workflow-sync)
- [Scripting and exit codes](/cli/scripting#exit-codes)