Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
64 commits
Select commit Hold shift + click to select a range
a020ac8
fix(sim-cli): check a workflow against the catalog its get printed with
waleedlatif1 Nov 19, 2026
307744a
fix(workflow-code): offline check refuses a cycle the edit adds betwe…
waleedlatif1 Nov 19, 2026
671bf3d
fix(sim-cli): cache source catalogs by content hash
waleedlatif1 Nov 19, 2026
6102039
fix(sim-cli): check each workspace workflow against the catalog its b…
waleedlatif1 Nov 19, 2026
cc0cdd0
fix(workflow-code): warn on a reference to an input the Start trigger…
waleedlatif1 Nov 20, 2026
c53d4b2
fix(sim-cli): write all output before exiting when stdout is a pipe
waleedlatif1 Nov 20, 2026
2fc27f3
fix(providers): send tool ids providers reject as provider-safe wire …
waleedlatif1 Nov 20, 2026
dbf5567
fix(workflows): refuse placing a block type hidden from the caller
waleedlatif1 Nov 20, 2026
22a0de2
fix(sim-cli): finish an in-flight source apply at Ctrl-C before exiting
waleedlatif1 Nov 20, 2026
29b9d1a
fix(sim-cli): a source create targets the workspace its starter was t…
waleedlatif1 Nov 20, 2026
5ee4bb3
fix(sim-cli): exit 13 from a status without login, and clearer cancel…
waleedlatif1 Nov 20, 2026
7915ade
docs(sim-cli): list every source exit code, create's --workspace, and…
waleedlatif1 Nov 20, 2026
74d80ea
fix(workspace-source): stage blobs in bodies the proxy forwards whole
waleedlatif1 Nov 19, 2026
b6fd91d
fix(workspace-source): compare a promotion with what the last one lef…
waleedlatif1 Nov 20, 2026
0de7691
fix(workspace-source): persist table column keys so every read prints…
waleedlatif1 Nov 20, 2026
92c3539
test(workspace-source): promoting managed rows converges
waleedlatif1 Nov 20, 2026
ebddf19
fix(workspace-source): name unsent paths, exit 1 at the findings cap,…
waleedlatif1 Nov 20, 2026
9a1c778
fix(workflow-code): say a hidden field is dropped, and which value hi…
waleedlatif1 Nov 20, 2026
1d48f5c
fix(workflow-code): bind renames of name and const by the lock, and q…
waleedlatif1 Nov 20, 2026
16330da
fix(workflow-code): point workflow-level findings at the name, name t…
waleedlatif1 Nov 20, 2026
e56fbcc
fix(sim-cli): source commands act on the workspace a directory was re…
waleedlatif1 Nov 20, 2026
1079302
feat(sim-cli): each source finding shown once, and the ids a write cr…
waleedlatif1 Nov 20, 2026
3cd992c
fix(workflow-code): W_JSON_REF_UNTYPED only where the edit wrote it, …
waleedlatif1 Nov 20, 2026
af0886a
feat(sim-cli): workflows source apply and create --deploy
waleedlatif1 Nov 20, 2026
63f7606
feat(sim-cli): source apply without --yes prints the plan instead of …
waleedlatif1 Nov 20, 2026
38797fe
fix(sim-cli): fail check on a dangling $ref in a new function file, a…
waleedlatif1 Nov 20, 2026
b1f74ae
fix(sim-cli): a source create goes to the workspace its starter was t…
waleedlatif1 Nov 20, 2026
efcbf80
fix(workflow-code): name added and removed blocks with their types, a…
waleedlatif1 Nov 20, 2026
3e73d32
fix(workspace-source): warn when a table column rename leaves a workf…
waleedlatif1 Nov 20, 2026
3ea9d3a
fix(workflow-code): leave out a container's subBlocks that block.data…
waleedlatif1 Nov 20, 2026
5b9cb84
Merge branch 'feat/dx-apply' into fix/workflow-code-staging-qa
waleedlatif1 Nov 20, 2026
fd511af
feat(sim-cli): sim workflows source params <builder> prints a builder…
waleedlatif1 Nov 20, 2026
b7301b6
docs(workflow-sdk): document $ref.loop and $ref.parallel iteration re…
waleedlatif1 Nov 20, 2026
7ca43a8
feat(sim-cli): source get prints a primer, which opens AGENTS.md, wit…
waleedlatif1 Nov 20, 2026
d63aa1b
perf(sim-cli): a source directory holds only the declarations of the …
waleedlatif1 Nov 20, 2026
160b5d9
perf(api): encode the source catalog and other large v2 source answer…
waleedlatif1 Nov 20, 2026
1ef34f4
Merge branch 'fix/e2e-ws' into fix/workflow-code-staging-qa
waleedlatif1 Nov 20, 2026
67dafef
chore(workflow-sdk): regenerate embedded workspace text after merging…
waleedlatif1 Nov 20, 2026
6d77cb1
fix(workflow-code): infer a name-and-const rename only on a strong id…
waleedlatif1 Nov 20, 2026
4efaa1b
Merge branch 'feat/dx-docs' into fix/workflow-code-staging-qa
waleedlatif1 Nov 20, 2026
95c6ee1
chore(docs): record the source params code example in the docs baseline
waleedlatif1 Nov 20, 2026
410082f
style(workflow-sdk): format the regenerated embedded workspace text
waleedlatif1 Nov 20, 2026
78a0737
Merge branch 'fix/e2e-diag' into fix/workflow-code-staging-qa
waleedlatif1 Nov 20, 2026
47b220c
fix(sim-cli): save a workspace apply before its best-effort stored-ed…
waleedlatif1 Nov 20, 2026
ae4a2f5
fix(workspace-code): keep a resource deleted in the target since the …
waleedlatif1 Nov 20, 2026
c3a86c9
fix(workflow-code): infer Function result kinds soundly and re-warn w…
waleedlatif1 Nov 20, 2026
f417f49
fix(workflow-code): name the visibleWhen clause that hides a field
waleedlatif1 Nov 20, 2026
8b7bd98
fix(workflow-sdk): print a special builder's core.d.ts signature and …
waleedlatif1 Nov 20, 2026
8e5aed6
fix(providers): bound a long tool id to the provider name limit
waleedlatif1 Nov 20, 2026
bd20481
fix(workflow-code): infer a rename from references in branches and su…
waleedlatif1 Nov 20, 2026
dae45ba
fix(sim-cli): sanitize a result field's display override
waleedlatif1 Nov 20, 2026
1e61d0e
fix(sim-cli): keep a collapsed warning's own message, and honor --ver…
waleedlatif1 Nov 20, 2026
96a51e6
fix(sim-cli): exit 130 at Ctrl-C on a line prompt
waleedlatif1 Nov 20, 2026
8348009
fix(sim-cli): drain stdout and stderr before re-raising a deferred in…
waleedlatif1 Nov 20, 2026
6f42bde
fix(sim-cli): degrade source status to the local view on a refused cr…
waleedlatif1 Nov 20, 2026
099950c
fix(sim-cli): print a saved write's result when the --deploy after it…
waleedlatif1 Nov 20, 2026
f23b958
docs(sim-cli): say an interrupted write waits up to 60s for its answer
waleedlatif1 Nov 20, 2026
1741ed9
fix(workspace-source): tell a full staging area apart from a body ove…
waleedlatif1 Nov 20, 2026
b8af837
fix(workspace-code): keep a knowledge base's document errors ahead of…
waleedlatif1 Nov 20, 2026
92b6812
fix(workspace-source): count a finished replacement among the documen…
waleedlatif1 Nov 20, 2026
da088b2
fix(workspace-source): warn on a column rename the live version of a …
waleedlatif1 Nov 20, 2026
d2cf60a
fix(api): stop encoding large v2 source answers in the route, which N…
waleedlatif1 Nov 20, 2026
d00c29e
Merge remote-tracking branch 'origin/staging' into fix/workflow-code-…
waleedlatif1 Nov 20, 2026
51738fe
test(sim-cli): use the shared sleep and test hooks in the terminal tests
waleedlatif1 Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 50 additions & 11 deletions apps/docs/content/docs/cli/reference.mdx

Large diffs are not rendered by default.

22 changes: 19 additions & 3 deletions apps/docs/content/docs/cli/scripting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -170,10 +170,22 @@ The CLI resends a request the API answers `429` only when sending it twice is sa
| `0` | Applied or created, or a dry run with no errors |
| `1` | The source has errors (each printed as `file:line:column` with its frame and hint), or command/request failure |
| `5` | The workflow changed since the directory was read (`409 SOURCE_STALE`): get it again, reapply the edit, and retry |
| `6` | The workflow is locked (`423`) |
| `6` | The workflow or its folder is locked (`423`, `E_APPLY_LOCKED`); a locked block exits `1` (`E_APPLY_LOCKED_BLOCK`) |
| `7` | The source is over the size limits (`413`) |
| `9` | Still rate limited (`429`) after the CLI's retries; nothing was written |
| `10` | `--dir` is a workflow folder of a workspace directory another `sim` command is using (`SOURCE_DIR_BUSY`); nothing was written: run it again once the other finished |
| `13` | `AUTH_REQUIRED`: not logged in, or the server refused the credential; nothing was sent |
| `14` | Run without `--yes` and with no terminal to ask: the plan was printed with no errors and nothing was written; run the same command with `--yes` |
| `130` | Interrupted (Ctrl-C). A write already sent is finished and saved into the directory first, waiting up to 60s for its answer; a second Ctrl-C, or no answer by then, stops at once and prints that it may have been written and how to check |

| Code | `sim workflows source status` or `sim workspaces source status` |
| --- | --- |
| `0` | Clean: nothing to apply, and the server changed nothing since the directory was read |
| `1` | Command/request failure |
| `7` | The source is too large for the server to read in one dry run |
| `11` | Local changes only: applying writes them |
| `12` | The server changed since the directory was read (drift, or a conflict with local changes) |
| `13` | `AUTH_REQUIRED`: not logged in, or the server refused the credential; the local changes are still shown |

| Code | `sim workflows source check` or `sim workspaces source check` |
| --- | --- |
Expand All @@ -192,11 +204,13 @@ The CLI resends a request the API answers `429` only when sending it twice is sa
| `0` | Applied, or a dry run with no errors |
| `1` | The source has errors, changes were held back for a secret or credential the workspace cannot satisfy, or command/request failure |
| `5` | A resource changed since the directory was read (`409 SOURCE_STALE`): get it again into a fresh directory, reapply the edit, and retry |
| `6` | A resource is locked (`423`) |
| `6` | A resource (a workflow or its folder, a table) is locked (`423`); a locked block exits `1` (`E_APPLY_LOCKED_BLOCK`) |
| `7` | The directory is over the size limits (`413`) |
| `8` | The apply stopped part-way: what was written is saved into the directory; apply again |
| `9` | Still rate limited (`429`) after the CLI's retries; nothing was written |
| `10` | Busy, retry: another apply is writing the workspace (`409 SOURCE_BUSY`), or another `sim workspaces source` command is using the same directory (`SOURCE_DIR_BUSY`); nothing was written: run the command again once the other finished |
| `13` | `AUTH_REQUIRED`: not logged in, or the server refused the credential; nothing was sent |
| `130` | Interrupted (Ctrl-C). A write already sent is finished and saved into the directory first, waiting up to 60s for its answer; a second Ctrl-C, or no answer by then, stops at once and prints that it may have been written and how to check |

Both waits default to 3600 seconds; `--wait-timeout 0` waits indefinitely. `SIM_TIMEOUT_SECONDS` independently bounds one API request. A timeout does not cancel the underlying run or operation.

Expand Down Expand Up @@ -403,12 +417,14 @@ jobs:

`check` runs first because it is offline and fast, and it regenerates `.sim/sdk/workspace.d.ts`, so the `tsc` step after it types resources the pull request adds. A workspace API key can apply tables, rows, knowledge bases, files, custom tools, MCP servers and credential bindings. Workflows, skills, secrets and deployments need a member's personal API key, and deployments need an admin. Apply rewrites files under the directory (each `.sim/base.json`, ids it allocated, values the server normalized), and the next apply compares with them, so the last step commits them back to the branch; `[skip ci]` keeps that commit from running the job again. Where the branch is protected, run `sim workspaces source get --dir workspace` on a new branch instead and open a pull request. After merging two branches that each applied, a dry run with no changes means the files match the workspace. Exit `5` means a resource changed since this branch's base: get the workspace into a fresh directory and carry the edit over. Exit `10` means another apply is writing the workspace (or another command is using the directory), so retry; the `concurrency` key keeps two runs of this job from overlapping.

To promote the same directory to a second workspace, add a step with `--to`:
To promote the same directory to a second workspace, add a step with `--to` before the step that commits the files back:

```bash
sim workspaces source apply --dir workspace --to "$PROD_WORKSPACE_ID" --yes
```

The promotion writes `workspace/.sim/targets/<workspaceId>.json`, what it left in that workspace. Committing it lets the next run tell a change made in that workspace since (kept, or exit `5` when the directory changed the same resource) from one to promote.

## Related docs

- [Output formats](/cli/output)
Expand Down
49 changes: 43 additions & 6 deletions apps/docs/content/docs/cli/workflows.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1337,7 +1337,7 @@ sim workflows source status [options]

</CommandTable>

Exit codes: 0 clean (nothing to apply, and the server changed nothing since the directory was read); 11 local changes only (applying writes them); 12 the server changed since the directory was read: drift (a resource edited, added or deleted there that the directory leaves alone) or a conflict (also changed here, so applying it is refused as stale), with or without local changes; 7 the source is too large for the server to read in one dry run; 1 the command failed. A server that cannot be reached is not a failure: the status shows the local changes only and says so (exit 0 or 11).
Exit codes: 0 clean (nothing to apply, and the server changed nothing since the directory was read); 11 local changes only (applying writes them); 12 the server changed since the directory was read: drift (a resource edited, added or deleted there that the directory leaves alone) or a conflict (also changed here, so applying it is refused as stale), with or without local changes; 7 the source is too large for the server to read in one dry run; 1 the command failed; 13 not logged in (AUTH_REQUIRED) or the credential was refused: the status shows the local changes only, then run `sim login`. A server that cannot be reached is not a failure: the status shows the local changes only and says so (exit 0 or 11).

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

Expand All @@ -1353,17 +1353,19 @@ sim workflows source create [options]

| Option | Required | Description |
| --- | --- | --- |
| `--verbose` | No | With --output json, also list info findings (such as blocks placed by autolayout). |
| `--dir <dir>` | Yes | Source directory: workflow.ts and functions/*. Without workflow.ts, writes a starter and the types instead (an error with --dry-run or --yes). |
| `--dry-run` | No | Check the source and show the outcome without creating anything. |
| `--name <name>` | No | The workflow name (default: the source's). |
| `--folder <path>` | No | The folder to create it in (default: the root). |
| `-y, --yes` | No | Create without asking for confirmation. |
| `--deploy` | No | After the write is saved, deploy the workflow (as `sim workflows deploy <workflowId>` does). |

</CommandTable>

Exit codes: 0 created (or a clean dry run, or a starter written); 1 the source has errors (each printed as file:line:column with its frame and hint), the workflow name is taken (SOURCE_NAME_TAKEN: pass --name), or the command failed; 6 the folder is locked; 7 the source is too large; 9 rate limited (HTTP 429) after the CLI's retries, so nothing was created: wait a minute and run it again. Exit 10 (busy, retry): --dir is a workflow folder of a workspace directory another sim command is using (SOURCE_DIR_BUSY); nothing was read or written. Run this one again once it finished.
Exit codes: 0 created (or a clean dry run, or a starter written); 1 the source has errors (each printed as file:line:column with its frame and hint), the workflow name is taken (SOURCE_NAME_TAKEN: pass --name), or the command failed (a starter is created in the workspace its types were written for unless --workspace names another); 6 the folder is locked; 7 the source is too large; 9 rate limited (HTTP 429) after the CLI's retries, so nothing was created: wait a minute and run it again; 14 without --yes and with no terminal to ask: the plan was printed with no errors and nothing was created (run the same command with --yes). Exit 10 (busy, retry): --dir is a workflow folder of a workspace directory another sim command is using (SOURCE_DIR_BUSY); nothing was read or written. Run this one again once it finished. Exit 13: not logged in, or the server refused the credential (AUTH_REQUIRED); nothing was sent. Run `sim login`, or fix or unset SIM_API_KEY when the key comes from it. Exit 130: interrupted (Ctrl-C). A write already sent is finished and saved into the directory first, waiting up to 60s for its answer; a second Ctrl-C, or no answer by then, stops at once and prints that it may have been written and how to check.

API request and response schemas: [createWorkflowFromSource](/api-reference/workflows/createWorkflowFromSource), [getSourceCatalog](/api-reference/catalog/getSourceCatalog), [getSourceResources](/api-reference/workflows/getSourceResources).
API request and response schemas: [createWorkflowFromSource](/api-reference/workflows/createWorkflowFromSource), [getSourceCatalog](/api-reference/catalog/getSourceCatalog), [getSourceResources](/api-reference/workflows/getSourceResources), [deployWorkflow](/api-reference/workflows/deployWorkflow).

### Apply a workflow source directory to a workflow draft

Expand All @@ -1387,16 +1389,18 @@ sim workflows source apply [workflowId] [options]

| Option | Required | Description |
| --- | --- | --- |
| `--verbose` | No | With --output json, also list info findings (such as blocks placed by autolayout). |
| `--dir <dir>` | Yes | Source directory: workflow.ts, functions/*, .sim/lock.json and .sim/base.json. |
| `--dry-run` | No | Check the source and show the outcome without saving or writing files. |
| `-y, --yes` | No | Apply without asking for confirmation. |
| `--deploy` | No | After the write is saved, deploy the workflow (as `sim workflows deploy <workflowId>` does). |
| `--allow-delete` | No | Delete blocks the source no longer declares; without it, an apply that deletes a block is refused. |

</CommandTable>

Exit codes: 0 applied (or a clean dry run); 1 the source has errors (each printed as file:line:column with its frame and hint) or the command failed; 5 the workflow changed since the directory was read (SOURCE_STALE, on a dry run too: get it again, reapply the edit, retry); 6 the workflow or its folder is locked; 7 the source is too large; 9 rate limited (HTTP 429) after the CLI's retries, so nothing was written: wait a minute and run it again. Exit 10 (busy, retry): --dir is a workflow folder of a workspace directory another sim command is using (SOURCE_DIR_BUSY); nothing was read or written. Run this one again once it finished.
Exit codes: 0 applied (or a clean dry run); 1 the source has errors (each printed as file:line:column with its frame and hint) or the command failed; 5 the workflow changed since the directory was read (SOURCE_STALE, on a dry run too: get it again, reapply the edit, retry); 6 the workflow or its folder is locked (E_APPLY_LOCKED; a locked block exits 1, E_APPLY_LOCKED_BLOCK); 7 the source is too large; 9 rate limited (HTTP 429) after the CLI's retries, so nothing was written: wait a minute and run it again; 14 without --yes and with no terminal to ask: the plan was printed with no errors and nothing was written (run the same command with --yes to apply it). Exit 10 (busy, retry): --dir is a workflow folder of a workspace directory another sim command is using (SOURCE_DIR_BUSY); nothing was read or written. Run this one again once it finished. Exit 13: not logged in, or the server refused the credential (AUTH_REQUIRED); nothing was sent. Run `sim login`, or fix or unset SIM_API_KEY when the key comes from it. Exit 130: interrupted (Ctrl-C). A write already sent is finished and saved into the directory first, waiting up to 60s for its answer; a second Ctrl-C, or no answer by then, stops at once and prints that it may have been written and how to check.

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

### Show the block catalog workflow source is checked against

Expand Down Expand Up @@ -1431,14 +1435,15 @@ sim workflows source check [options]
| `--dir <dir>` | No | Source directory: workflow.ts, functions/* and .sim/. Defaults to `.`. |
| `--strict` | No | Fail on the warnings listed below in every block, not only new ones. |
| `--no-strict` | No | Never fail on a warning. |
| `--verbose` | No | With --output json, also list info findings (such as blocks placed by autolayout). |

</CommandTable>

Compiles workflow.ts (and the function files it names) with the compiler the server runs, against the workspace's block catalog the last get or create cached, and prints the findings as the dry run does. No request is made. It covers the source itself (syntax, builders, params, references, wiring). In a workflow folder of a workspace directory (workflows/&lt;key&gt;), it reads the workspace's .sim/base.json and also checks env names, resource keys and table columns against what the directory declares. The dry run still checks what only the server knows (stored values, deployment), so run it before applying. A check also adds the blocks the source now uses to the CLI's tsconfig.json, so tsc type-checks a block the edit added; in a workspace directory it also regenerates .sim/sdk/workspace.d.ts, so tsc types each workflow's inputs as its files declare them.

Exit codes: 0 no errors; 1 errors (each printed as file:line:column with its frame and hint), or no cached catalog (run the get once). With --output json, stdout is one document that also lists every finding under diagnostics.

These warnings, which an apply saves as written, fail the check as errors on every block the lock does not bind (a block added since the get, or every block of a new workflow): W_REQUIRED_MISSING, W_UNKNOWN_OPTION, W_UNKNOWN_OUTPUT_PATH, W_VALUE_KIND, W_OUT_OF_RANGE, W_LITERAL_SECRET, W_TABLE_UNKNOWN_COLUMN, W_CHILD_INPUT_UNKNOWN, W_BRANCH_UNWIRED. --strict fails on them in every block, except W_BRANCH_UNWIRED on a block the lock binds (the stored workflow may hold it, and the server then stays quiet); --no-strict never fails on a warning.
These warnings, which an apply saves as written, fail the check as errors on every block the lock does not bind (a block added since the get, or every block of a new workflow): W_REQUIRED_MISSING, W_UNKNOWN_OPTION, W_UNKNOWN_OUTPUT_PATH, W_VALUE_KIND, W_OUT_OF_RANGE, W_LITERAL_SECRET, W_TABLE_UNKNOWN_COLUMN, W_CHILD_INPUT_UNKNOWN, W_BRANCH_UNWIRED, W_UNRESOLVED_REF. --strict fails on them in every block, except W_BRANCH_UNWIRED on a block the lock binds (the stored workflow may hold it, and the server then stays quiet); --no-strict never fails on a warning. W_JSON_REF_UNTYPED is reported only on blocks the lock does not bind, and with --strict on every block.

### Show the content of the changes in a workflow source directory

Expand Down Expand Up @@ -1472,6 +1477,38 @@ Without --server, each file created, edited or deleted since the directory was r

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

### Print a builder's params and outputs from the cached block catalog

Offline.

```bash
sim workflows source params <builder> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `builder` | Yes | Builder path (table.upsertRow, agent, trigger.schedule) or namespace |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--dir <dir>` | No | Source directory whose catalog to read. Defaults to `.`. |

</CommandTable>

Prints a builder's params (required first, with enums and defaults), the gate field that picks which others apply, and its outputs, from the block catalog the last get, create or check cached. No request is made. &lt;builder&gt; is the dotted builder path as source writes it: table.upsertRow, agent, trigger.schedule, slack.sendMessage (slack.tool.sendMessage names the same builder). A namespace (gmail, trigger.gmail) lists its builders; a construct core.d.ts declares (loop, parallel, t, env) prints its declaration. Run it from a workflow or workspace source directory, or pass --dir.

Exit codes: 0 printed; 1 no builder or namespace of that name (the closest one is named), or no cached catalog (run a get once).

### List the tables, knowledge bases, credentials, workflows, skills, custom tools, MCP servers and env names source can name

```bash
Expand Down
Loading