Skip to content

feat(files): workspace file version history over the v2 API, CLI, and MCP #7997

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
waleedlatif1 merged 11 commits into from
Sep 19, 2026
Merged

feat(files): workspace file version history over the v2 API, CLI, and MCP #7997

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
5327ce8
feat(files): workspace file version history over the v2 API, CLI, and…
waleedlatif1 Sep 19, 2026
35ac722
fix(files): address review feedback on file version history
waleedlatif1 Sep 19, 2026
98f01a8
chore(db): regenerate file version migration after staging's 0364
waleedlatif1 Sep 19, 2026
e43846c
improvement(files): scope version rows to the write's workspace and n…
waleedlatif1 Sep 19, 2026
dc4f76c
fix(files): release purged file history atomically with restore
waleedlatif1 Sep 19, 2026
cc2cbc0
fix(files): release file history through the outbox after the current…
waleedlatif1 Sep 19, 2026
2c65f4b
fix(files): release purged history inside the file-row purge transaction
waleedlatif1 Sep 19, 2026
18188ce
fix(files): resolve metadata version from the record's own storage key
waleedlatif1 Sep 19, 2026
5873aff
fix(files): never pair a stale file record with a newer version number
waleedlatif1 Sep 19, 2026
29a598e
improvement(files): simplify file version history internals
waleedlatif1 Sep 19, 2026
b511c3d
Merge remote-tracking branch 'origin/staging' into feat/file-versions…
waleedlatif1 Sep 19, 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
6 changes: 6 additions & 0 deletions .github/workflows/test-build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,12 @@ jobs:
KNOWLEDGE_ACL_TEST_DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_auth_scim
run: bunx vitest run --mode integration lib/workspace-files/search/dispatcher.integration.ts

- name: Verify workspace file version history on PostgreSQL 17
working-directory: apps/sim
env:
KNOWLEDGE_ACL_TEST_DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/sim_auth_scim
run: bunx vitest run --mode integration lib/uploads/contexts/workspace/__integration__/file-versions.integration.ts

- name: Verify file search trigram estimate against pg_trgm
working-directory: apps/sim
env:
Expand Down
157 changes: 157 additions & 0 deletions apps/docs/content/docs/cli/files.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,163 @@ sim files delete <fileId> [options]

</CommandTable>

## Permanently delete a previous version of a file

```bash
sim files versions delete <fileId> <version> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

**Options**

<CommandTable>

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

</CommandTable>

## Show the metadata of one version of a file

```bash
sim files versions describe <fileId> <version>
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

## List the recorded versions of a file

```bash
sim files versions list <fileId> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `version`. |
| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |

</CommandTable>

## Read the text content of one version of a file

```bash
sim files versions read <fileId> <version> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
| `--offset <value>` | No | First line to return, 1-based. Absent starts at the first line. |
| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |

</CommandTable>

## Make a previous version of a file current again

```bash
sim files versions revert <fileId> <version> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--expected-current-version <value>` | No | Revert only while this is still the current version; otherwise the request fails with `409`. Omit to revert whatever is current. Collaborative edits and repeated workflow writes that fold into the current version keep its number. |

</CommandTable>

## Download the content of one version of a file

```bash
sim files versions download <fileId> <version> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `-o, --output-file <path>` | No | Write content to a file instead of stdout. |
| `--force` | No | Overwrite --output-file if it already exists. |

</CommandTable>

## Apply one exact or anchor-based edit to a text file

```bash
Expand Down
169 changes: 169 additions & 0 deletions apps/docs/content/docs/cli/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -909,6 +909,175 @@ sim files delete <fileId> [options]

</CommandTable>

### sim files versions delete

Permanently delete a previous version of a file

```bash
sim files versions delete <fileId> <version> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

**Options**

<CommandTable>

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

</CommandTable>

### sim files versions describe

Show the metadata of one version of a file

```bash
sim files versions describe <fileId> <version>
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

### sim files versions list

List the recorded versions of a file

```bash
sim files versions list <fileId> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `version`. |
| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |

</CommandTable>

### sim files versions read

Read the text content of one version of a file

```bash
sim files versions read <fileId> <version> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
| `--offset <value>` | No | First line to return, 1-based. Absent starts at the first line. |
| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |

</CommandTable>

### sim files versions revert

Make a previous version of a file current again

```bash
sim files versions revert <fileId> <version> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `--expected-current-version <value>` | No | Revert only while this is still the current version; otherwise the request fails with `409`. Omit to revert whatever is current. Collaborative edits and repeated workflow writes that fold into the current version keep its number. |

</CommandTable>

### sim files versions download

Download the content of one version of a file

```bash
sim files versions download <fileId> <version> [options]
```

**Arguments**

<CommandTable>

| Argument | Required | Description |
| --- | --- | --- |
| `fileId` | Yes | File identifier. |
| `version` | Yes | Version number. |

</CommandTable>

**Options**

<CommandTable>

| Option | Required | Description |
| --- | --- | --- |
| `-o, --output-file <path>` | No | Write content to a file instead of stdout. |
| `--force` | No | Overwrite --output-file if it already exists. |

</CommandTable>

### sim files edit

Apply one exact or anchor-based edit to a text file
Expand Down
11 changes: 9 additions & 2 deletions apps/docs/content/docs/platform/enterprise/data-retention.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,12 @@ Controls how long **Chat data** is kept, including:
- Run checkpoints and async tool calls
- Inbox tasks

### Previous file versions

Every change to a file's content keeps the previous content as a version you can read or revert to through the API, CLI, or MCP server. This setting controls how long a version is kept after a newer one replaces it. The newest ten versions of each file are always kept, whatever their age.

Without a setting, previous versions are kept until a file reaches 500 of them. The setting isn't on the settings page yet: set `fileVersionRetentionHours` through the data retention API, either for the organization or in a workspace override.

Each setting is independent. You can configure a short log retention period alongside a long soft deletion cleanup period, or any combination that fits your compliance requirements.

---
Expand Down Expand Up @@ -186,16 +192,17 @@ Once enabled, retention settings are configurable through **Settings → Organiz

### Scheduling the deletion pass

`DATA_RETENTION_ENABLED` permits deletion; it does not perform it. Deletion runs when a scheduled request reaches one of three endpoints, each authenticated with a bearer token equal to `CRON_SECRET`:
`DATA_RETENTION_ENABLED` permits deletion; it does not perform it. Deletion runs when a scheduled request reaches one of four endpoints, each authenticated with a bearer token equal to `CRON_SECRET`:

| Category | Endpoint |
|----------|----------|
| Execution and job logs | `GET /api/logs/cleanup` |
| Soft-deleted resources | `GET /api/cron/cleanup-soft-deletes` |
| Chats and Chat runs | `GET /api/cron/cleanup-tasks` |
| Previous file versions | `GET /api/cron/cleanup-file-versions` |

<Callout type="warn">
Neither shipped deployment schedules these three endpoints — not the Helm chart, not Docker Compose's `cron` service. An operator who sets `DATA_RETENTION_ENABLED=true` alone still deletes nothing. Add them to `cronjobs.jobs`, or call them daily from an external scheduler.
Neither shipped deployment schedules these four endpoints — not the Helm chart, not Docker Compose's `cron` service. An operator who sets `DATA_RETENTION_ENABLED=true` alone still deletes nothing. Add them to `cronjobs.jobs`, or call them daily from an external scheduler.
</Callout>

```bash
Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/docs/platform/enterprise/self-hosted.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,10 +86,11 @@ Persist that value as `CRON_SECRET` on the app **and** on whatever calls these e
| Retention — logs | `GET /api/logs/cleanup` | Daily | **No** — schedule it yourself |
| Retention — soft deletes | `GET /api/cron/cleanup-soft-deletes` | Daily | **No** — schedule it yourself |
| Retention — Chat tasks | `GET /api/cron/cleanup-tasks` | Daily | **No** — schedule it yourself |
| Retention — file versions | `GET /api/cron/cleanup-file-versions` | Daily | **No** — schedule it yourself |
| OAuth token cleanup | `GET /api/cron/cleanup-oauth-tokens` | Hourly | Yes — Helm and Docker Compose both call it |

<Callout type="warn">
Both shipped deployments schedule the data-drain dispatcher and OAuth token cleanup, but **not** the three configurable data-retention endpoints. Setting `DATA_RETENTION_ENABLED=true` alone deletes no retained product data — those windows are evaluated only when one of the three endpoints is called. Add them to `cronjobs.jobs` yourself, or drive them from an external scheduler.
Both shipped deployments schedule the data-drain dispatcher and OAuth token cleanup, but **not** the four configurable data-retention endpoints. Setting `DATA_RETENTION_ENABLED=true` alone deletes no retained product data — those windows are evaluated only when one of the four endpoints is called. Add them to `cronjobs.jobs` yourself, or drive them from an external scheduler.

OAuth token cleanup runs independently of sign-in activity, removing expired and revoked credentials. See [Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim) for provider configuration.
</Callout>
Expand Down
Loading
Loading