Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
8 changes: 7 additions & 1 deletion .github/workflows/publish-sim-cli.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,14 @@ on:
paths:
- 'packages/sim-cli/**'
# The build bundles its workspace dependencies, so a change there
# changes what ships.
# changes what ships. `bun run check:sim-cli-bundle` fails when this
# list and the bundle's workspace packages disagree.
- 'packages/table-cells/**'
Comment thread
waleedlatif1 marked this conversation as resolved.
Resolved
- 'packages/utils/**'
- 'packages/workflow-code/**'
- 'packages/workflow-sdk/**'
- 'packages/workflow-types/**'
- 'packages/workspace-code/**'
# A change to how the package is built or published has to republish it.
- '.github/workflows/publish-sim-cli.yml'

Expand Down
11 changes: 8 additions & 3 deletions apps/docs/content/docs/cli/scripting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -168,12 +168,12 @@ The CLI resends a request the API answers `429` only when sending it twice is sa
| Code | `sim workflows source apply` or `create` |
| --- | --- |
| `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 |
| `1` | The source has errors (each printed as `file:line:column` with its frame and hint), `create`'s workflow name is taken (`SOURCE_NAME_TAKEN`: pass `--name`), 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 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 |
| `10` | Busy, retry: another `sim` command is using `--dir`, or the workspace directory it is a workflow folder of (`SOURCE_DIR_BUSY`); nothing was read or 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 |
Expand All @@ -183,6 +183,7 @@ The CLI resends a request the API answers `429` only when sending it twice is sa
| `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 |
| `10` | `sim workspaces source status` only: another `sim workspaces source` command is using the directory (`SOURCE_DIR_BUSY`); nothing was read: run it again once the other finished |
| `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 |
Expand All @@ -191,13 +192,17 @@ The CLI resends a request the API answers `429` only when sending it twice is sa
| --- | --- |
| `0` | No errors (warnings may still print) |
| `1` | The source has errors, or a warning that fails the check on a block the edit added (see `--strict`), or no block catalog is cached: run the get once |
| `10` | `sim workspaces source check` only: another `sim workspaces source` command is using the directory (`SOURCE_DIR_BUSY`); nothing was read: run it again once the other finished |

| Code | `sim workflows source get --dir` or `sim workspaces source get` |
| --- | --- |
| `0` | Written |
| `1` | The directory holds edits no apply has saved (`SOURCE_LOCAL_EDITS`) or another workflow's source (`SOURCE_WORKFLOW_MISMATCH`): apply them, get into another directory, or pass `--force`; or command/request failure |
| `1` | The directory holds edits no apply has saved (`SOURCE_LOCAL_EDITS`) or another workflow's source (`SOURCE_WORKFLOW_MISMATCH`): apply them, get into another directory, or pass `--force`; it is the other kind of source directory (`SOURCE_DIR_KIND_MISMATCH`, even with `--force`); for a workspace, `--workspace` names another workspace than the one the directory was read from (`SOURCE_OTHER_WORKSPACE`) or a downloaded binary file does not match its listing (`SOURCE_BLOB_MISMATCH`); or command/request failure |
| `7` | The workflow, or a kind of resource, is too large for one directory |
| `9` | Still rate limited (`429`) after the CLI's retries; nothing was written |
| `10` | Busy, retry: another `sim` command is using the directory (or, for a workflow folder, its workspace directory) (`SOURCE_DIR_BUSY`); nothing was read or written: run it again once the other finished |
| `13` | `AUTH_REQUIRED`: not logged in, the login expired, or the server refused the credential; nothing was read or written: run `sim login` and the get again |
| `130` | Interrupted (Ctrl-C): run the get again |

| Code | `sim workspaces source apply` |
| --- | --- |
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/content/docs/platform/enterprise/audit-logs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ Events use identifiers such as `resource.action`. These categories are represent
| Links | `sim_link.created`, `sim_link.updated`, `sim_link.deleted` |
| Exports and drains | `audit_logs.exported`, `data_drain.created`, `data_drain.updated`, `data_drain.ran`, `data_drain.tested` |

Authentication failures and password-reset requests use an anonymous actor and record the target account separately. Impersonation and administrative session revocations identify the operator and target organization. Table-row mutations record summaries and counts without copying row contents.
Authentication failures and password-reset requests use an anonymous actor and record the target account separately. Impersonation and administrative session revocations identify the operator and target organization. Table-row mutations record summaries and counts without copying row contents. A workflow or workspace written from source by the CLI (`workflow.created`, `workflow.updated` or `workspace.updated`) records `metadata.client` as `cli` and, when the source directory is in a git repository and `git` can read them, `metadata.gitSha` (the commit checked out) and `metadata.repo` (the `origin` remote URL, with any credentials removed). Either may be absent, for example `repo` in a repository with no `origin`.

When a workflow run makes the same kind of change to a table many times in quick succession, such as inserting rows in a loop, the repeats are merged into one `table.updated` entry. The merged entry keeps every row ID in `metadata.rowIds`, sums the counts, and records in `metadata.rollup` how many changes it covers and when the first and last happened. The actor of any workflow-made entry names the workflow (`metadata.actor.workflowId`) and the run (`metadata.actor.executionId`). Credential use by a workflow run is merged the same way: one `credential.accessed` entry per credential, counting the repeats, that names the workflow (`metadata.workflowId`) and the run (`metadata.executionId`).

Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/docs/workflows/code.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ Claude Code, Cursor, Codex and other coding agents work from a directory that `g
2. Edit `workflow.ts`.
3. `sim workflows source check --dir <dir>` compiles it offline.
4. `sim workflows source status --dir <dir>` shows what changed and what to run next.
5. `sim workflows source apply --dir <dir> --dry-run`, then `--yes`, saves the draft.

To write a block the workflow does not use yet, `sim workflows source params <builder>` (for example `table.upsertRow` or `trigger.schedule`) prints its params, required ones first with their options and defaults, and its outputs, from the cached block catalog without a request. A namespace such as `gmail` lists its builders.
5. `sim workflows source apply --dir <dir> --dry-run`, then `--yes`, saves the draft.

For a whole workspace, use `sim workspaces source` with the same steps; see [Workspace as code](/workflows/workspace-code).

Expand Down Expand Up @@ -206,6 +206,7 @@ Run `sim workflows source apply <workflowId> --dir <dir> --dry-run` in CI to cat
- **Commit** `workflow.ts`, `functions/`, `.sim/lock.json`, `.sim/base.json`, `.sim/written.json`, `tsconfig.json` and `.gitattributes`. CI finds the workflow from `workflowId` in `.sim/base.json`, and `status` and `get` use `.sim/written.json` to tell your edits apart from what the CLI last wrote.
- **Optionally gitignore** `.sim/sdk/`, the generated type declarations of the blocks in use (a few dozen files); `get` and `check` write them again. Gitignore `tsconfig.full.json`, which names the CLI's cache on your machine; `check` writes it again. A single-workflow directory gets no `.gitignore`, so add the lines yourself.
- **A whole workspace** in one repository, with dry runs on pull requests, apply on merge and promotion from one workspace to another, is covered in [Git and CI](/workflows/workspace-code#git-and-ci) and [Promote to another workspace](/workflows/workspace-code#promote-to-another-workspace).
- **Git provenance:** in a git repository, `apply` and `create` send the commit checked out (`HEAD`) and the `origin` remote URL, with any credentials, query or fragment removed, as `provenance.gitSha` and `provenance.repo`, each only when `git` can read it (a repository with no `origin` sends only the commit). A saved write records what was sent in its [audit log](/platform/enterprise/audit-logs) entry (`workflow.updated` or `workflow.created`). A directory outside a repository sends neither.
- **Credentials:** use a personal API key (**Settings → Sim API keys**, passed as `SIM_API_KEY`) or an OAuth login, not a workspace API key. Saving and dry-running source act as a person, so a workspace key is refused with `403`. Set `SIM_WORKSPACE` unless you pass `--workspace`, and `SIM_ENDPOINT` if you use a self-hosted Sim. See [Authenticating CI](/cli/authentication#authenticating-ci).

## Working with other people
Expand Down
2 changes: 2 additions & 0 deletions apps/docs/content/docs/workflows/workspace-code.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,8 @@ Commit the record with the rest of the directory, so a promotion from CI or anot

Commit the whole directory, including `.sim/`: its base files are what an apply compares with, from any clone. The generated `.gitignore` leaves out only temporary files. A fresh clone can run `check`, `apply --dry-run` and `apply` with nothing else. See [Workspace source in CI](/cli/scripting#workspace-source-in-ci) for a GitHub Actions setup.

In a git repository, `apply` sends the commit checked out (`HEAD`) and the `origin` remote URL, with any credentials, query or fragment removed, as `provenance.gitSha` and `provenance.repo`, each only when `git` can read it (a repository with no `origin` sends only the commit). An apply that writes records what was sent in its `workspace.updated` [audit log](/platform/enterprise/audit-logs) entry. A directory outside a repository sends neither.

## Good to know

- Secret values never appear. Workflows read environment variables as `env.NAME`, tool code as `$env.NAME`, and credentials by key.
Expand Down
1 change: 1 addition & 0 deletions biome.json
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
"!**/packages/workflow-sdk/src/codegen/core-text.generated.ts",
"!**/packages/workflow-sdk/src/codegen/cookbook-text.generated.ts",
"!**/packages/workflow-sdk/src/codegen/workspace-cookbook-text.generated.ts",
"!**/packages/workflow-sdk/src/codegen/workspace-text.generated.ts",
"!**/packages/workflow-sdk/cookbook/workspace/tools/*.js",
"!**/apps/docs/.content",
"!**/apps/desktop/release",
Expand Down
2 changes: 1 addition & 1 deletion bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@
"check:mcp-operations": "bun run scripts/generate-v2-mcp-operations.ts --check",
"generate:cli-docs": "bun run scripts/generate-cli-docs.ts",
"check:cli-docs": "bun run scripts/generate-cli-docs.ts --check",
"check:sim-cli-bundle": "bun run scripts/check-sim-cli-bundle.ts",
"generate:workflow-sdk-embedded-text": "bun run packages/workflow-sdk/scripts/generate-embedded-text.ts",
"check:workflow-sdk-embedded-text": "bun run packages/workflow-sdk/scripts/generate-embedded-text.ts --check",
"generate:v2-route-table": "bun run scripts/generate-v2-route-table.ts",
"check:v2-route-table": "bun run scripts/generate-v2-route-table.ts --check",
"check:canonical-index": "bun run scripts/check-canonical-index-surface.ts",
Expand Down
9 changes: 9 additions & 0 deletions packages/sim-cli/THIRD_PARTY_LICENSES
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
The Sim CLI bundle includes the following third-party software.

@babel/parser
Copyright (C) 2012-2014 by various contributors (see AUTHORS)

@noble/hashes
Copyright (c) 2022 Paul Miller (https://paulmillr.com)

chalk
Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)

Expand All @@ -22,6 +28,9 @@ retry
Copyright (c) 2011 Tim Koschützki (tim@debuggable.com)
Copyright (c) 2011 Felix Geisendörfer (felix@debuggable.com)

zod
Copyright (c) 2025 Colin McDonnell

Each dependency above is licensed under the MIT License:

Permission is hereby granted, free of charge, to any person obtaining a copy
Expand Down
2 changes: 1 addition & 1 deletion packages/sim-cli/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "sim",
"version": "2.2.0",
"version": "2.3.0",
"description": "Sim CLI - talk to the Sim API from your terminal",
"type": "module",
"imports": {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -814,24 +814,29 @@ describe('workspaces source apply', () => {
expect(request).not.toHaveBeenCalled()
})

it('removes the code file of a tool the apply reprinted as stored(), from disk and the record', async () => {
const declaration = (code: string) =>
`// @sim-sdk 1\nexport default defineTool({ title: 'Lookup', code: ${code} })\n`
write('tools/lookup.ts', declaration("codeFile('./lookup.js')"))
it('keeps the code file of a tool the apply reprinted as stored(), warns, and never sends it again', async () => {
const schema = "{ type: 'function', function: { name: 'lookup', parameters: {} } }"
const declaration = (call: 'codeFile' | 'stored', code: string) =>
`// @sim-sdk 1\nimport { ${call}, defineTool } from '@sim/workflow-sdk/workspace'\n\nexport default defineTool({ title: 'Lookup', schema: ${schema}, code: ${code} })\n`
write('tools/lookup.ts', declaration('codeFile', "codeFile('./lookup.js')"))
write('tools/lookup.js', 'return 1\n')
write('tools/other.js', 'return 2\n')
request.mockResolvedValue(
answer({
applied: [{ kind: 'custom-tool', key: 'lookup', action: 'update', id: 'tool_1' }],
files: { 'tools/lookup.ts': declaration('stored()') },
files: { 'tools/lookup.ts': declaration('stored', 'stored()') },
})
)

await apply('--yes')

expect(bodies()[0].files['tools/lookup.js']).toBe('return 1\n')
expect(existsSync(join(dir, 'tools/lookup.js'))).toBe(false)
// The person's only copy of the code: like a workflow's function file, it is never deleted.
expect(readFileSync(join(dir, 'tools/lookup.js'), 'utf8')).toBe('return 1\n')
expect(readFileSync(join(dir, 'tools/other.js'), 'utf8')).toBe('return 2\n')
expect(vi.mocked(console.error).mock.calls.flat().join('\n')).toContain(
'warning: tools/lookup.js is no longer named by tools/lookup.ts'
)
const record = JSON.parse(readFileSync(join(dir, '.sim/written.json'), 'utf8'))
expect(Object.keys(record.files)).toContain('tools/lookup.ts')
expect(Object.keys(record.files)).not.toContain('tools/lookup.js')
Expand Down
33 changes: 23 additions & 10 deletions packages/sim-cli/src/commands/protocol/workspace-source-apply.ts
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ import {
ONLY_KINDS_HELP,
parseKinds,
readWorkspaceDir,
toolOfCodeFile,
type WorkspaceSubmission,
} from './workspace-source-dir'

Expand Down Expand Up @@ -353,9 +354,9 @@ async function deletedRecordedPaths(

/**
* The text files the directory sent for a resource the apply reprinted that the reprint no longer
* holds: a tool whose code the server keeps as `stored()` (a credential in it) is reprinted
* without `tools/<key>.js`, which left on disk would refuse the next apply (`E_TOOL_CODE`).
* Workflow folders keep files no lock named, so their function files are pruned by lock instead
* holds, such as a tool whose code the server keeps as `stored()` (a credential in it), reprinted
* without `tools/<key>.js` ({@link saveApplied} keeps that one on disk). Workflow folders keep
* files no lock named, so their function files are pruned by lock instead
* ({@link orphanedWorkflowFiles}); blobs are never reprinted.
*/
function droppedResourceFiles(
Expand Down Expand Up @@ -385,8 +386,10 @@ function droppedResourceFiles(
* their digests in `.sim/written.json` (`written` is what it held), beside the digests of the
* blobs the server now holds. The function files a written workflow no longer uses, and the files
* a reprinted resource no longer has, are removed from disk and the record; the record also drops
* the files of resources the apply deleted ({@link deletedRecordedPaths}). `records` are the
* stored-edges records of the workflows it reprinted.
* the files of resources the apply deleted ({@link deletedRecordedPaths}). A tool's code file the
* reprint no longer names is the person's only copy of that code, so like a workflow's function
* file it stays on disk, leaves the record, and is named in a warning; no apply sends it again.
* `records` are the stored-edges records of the workflows it reprinted.
*/
async function saveApplied(
dir: string,
Expand All @@ -396,13 +399,18 @@ async function saveApplied(
records: ReadonlyArray<readonly [string, string]>
): Promise<void> {
assertWorkspacePaths(Object.keys(data.files))
const orphaned = [
...(await orphanedWorkflowFiles(dir, data.files, written.digests)),
...droppedResourceFiles(submission.files, data.files),
]
const toolCode: Array<{ path: string; declaration: string }> = []
const orphaned = await orphanedWorkflowFiles(dir, data.files, written.digests)
for (const path of droppedResourceFiles(submission.files, data.files)) {
Comment thread
waleedlatif1 marked this conversation as resolved.
Resolved
const tool = toolOfCodeFile(path)
if (tool) toolCode.push({ path, declaration: tool.declaration })
else orphaned.push(path)
}
const kept = { ...written.digests, ...appliedBlobDigests(submission, data.base) }
const deleted = await deletedRecordedPaths(dir, written.digests, submission.kinds, data.base)
for (const path of [...orphaned, ...deleted]) delete kept[path]
for (const path of [...orphaned, ...deleted, ...toolCode.map(({ path }) => path)]) {
delete kept[path]
}
const record = writtenRecord(
data.files,
kept,
Expand All @@ -417,6 +425,11 @@ async function saveApplied(
],
remove: [...orphaned, ...removedWorkflowRecords(deleted)],
})
for (const { path, declaration } of toolCode) {
printError(
`warning: ${path} is no longer named by ${declaration} (its code is now kept as stored() or printed inline), so it was left on disk as written and no apply sends it: delete it, or name it again with codeFile(). Never commit one that holds a credential.`
)
}
}

/** The workflow a directory's base belongs to (a workflow source directory), or `null`. */
Expand Down
Loading
Loading